Skip to content
Livstick Developers
v3 Request access

Containers

A container holds one message (single) or a gallery of messages (gallery). Its mode is fixed when it is created: the API refuses to change it afterwards, and a widget always renders the mode the container was created with.

API v3.1 Base URL https://<client-api-host>/api/v3.1

Lifecycle

Create a container, read it back, list them, and correct the fields that may change.

Method POST /containers

Scope containers:write

Create a container with its mode, notifications and contacts. Returns the edit key once.

A request body with an unknown field is refused with 400 DATA_INVALID. The mode is required: there is no default in v3.1.

Parameters

Name In Type Required Description
crid Body string Required Your reference for the container, 1 to 128 characters: letters, digits, dot, underscore, colon and hyphen, starting with a letter or digit.
mode Body "single" | "gallery" Required Fixed for the life of the container.
language Body string Optional Identifier of a language enabled on the platform.
codeGroup Body string Optional Public identifier of a code group of the platform. An unknown value is ignored.
sender Body object Optional firstName and lastName (50 characters at most each), email (valid address, 254 characters at most).
recipient Body object Optional firstName, lastName, email, and phone in E.164 form. A channel field is refused: SMS is outside v3.1.
gallery Body object Optional title, 80 characters at most. Only valid when mode is gallery.
notifications Body object Optional Keys organizer, contributors and recipient. See the notifications field group below.
additionalData Body object Optional Up to 20 keys of letters, digits and underscores, with string (500 characters at most), number or boolean values. A key containing mail or phone is refused.

Response

json 201 Created (200 on a replay) 
{
  "crid": "AUB-20481",
  "urid": "7kq2mx9k3p",
  "mode": "gallery",
  "state": "recording_open",
  "editKey": "<uuid>",
  "notifications": {…},
  "links": {"recordingUrl": "…", "previewUrl": "…"},
  "platformId": "…",
  "createdAt": "…"
}

Notes

  • editKey is returned on creation and on a replay, so a lost network response does not lose it. It is never returned by a read.
  • Replay: a crid that already exists on the platform, created by v3.1, returns 200 with the existing container. Mode, notifications and contacts in the body are ignored.
  • A crid that exists but was created by another API returns 409 CRID_IN_USE.
  • Contacts are stored for the e-mail and the card, and are never returned by v3.1 reads.

Method GET /containers

Scope containers:read

List the containers created through v3.1 on the platform of the key, newest first.

Parameters

Name In Type Required Description
limit Query integer Optional From 1 to 100. Default 20.
skip Query integer Optional Offset, 0 or more.
order Query "createdAt" | "-createdAt" Optional Sort order. Default -createdAt.

Response

json 200 OK 
{"items": [ … ], "total": 42, "limit": 20, "skip": 0}

Method GET /containers/{crid}

Scope containers:read

Read one container: its mode, state, notifications and gallery counters.

Parameters

Name In Type Required Description
crid Path string Required Your reference for the container.

Response

json 200 OK 
{
  "crid": "AUB-20481",
  "urid": "7kq2mx9k3p",
  "mode": "gallery",
  "state": "recording_open",
  "shipped": false,
  "shippedAt": null,
  "notifiedAt": null,
  "notifications": {…},
  "gallery": {"title": "…", "messageCount": 5, "listedCount": 4, "closed": false},
  "links": {…},
  "createdAt": "…",
  "updatedAt": "…"
}

Notes

  • gallery is null for a single container.
  • state is recording_open while the container accepts a message (a single container without a main message, or a gallery that is not closed), and recording_closed otherwise.
  • listedCount counts the messages that are listed publicly, as opposed to held or pending.

Method PATCH /containers/{crid}

Scope containers:write

Correct the fields that may change after creation. Sending mode, or gallery.mode, is refused.

Partial update. An empty body is refused with 400 DATA_INVALID. A field that is not listed in the create body is refused.

Parameters

Name In Type Required Description
crid Path string Required Current reference for the container.
newcrid Body string Optional A new reference. Tokens already issued keep working: they carry the container identifier, not the crid.
shipmentCarrier Body string Optional A carrier from the platform's allowed list.
shipmentCode Body string Optional Tracking code, 100 characters at most.
language Body string Optional Identifier of a language enabled on the platform.
sender Body object Optional Same rules as on creation.
recipient Body object Optional Same rules as on creation.
notifications Body object Optional Merged key by key into the stored settings.
gallery Body object Optional title only, and only for a gallery.

Response

json 200 OK 
The container, in the same shape as the read.

Notes

  • A newcrid already in use on the platform returns 409 CRID_IN_USE.

Actions

Calls that act on a container without changing its mode or its messages.

Method POST /containers/{crid}/notify

Scope containers:notify

Ask Livstick to tell the recipient that a message is ready.

Parameters

Name In Type Required Description
crid Path string Required Your reference for the container.
recipient Body object Optional Optional firstName and email, written before the notification is queued.

Response

json 200 OK 
{"result": "ok", "notifiedAt": "…", "emailQueued": true}

Notes

  • A single container needs a listed main message, and a gallery needs at least one listed message. Otherwise the call returns 409 MESSAGE_MISSING.
  • Whether an e-mail is sent depends on the recipient notification setting. With the setting to client, Livstick does not send the e-mail, and emailQueued is false.
  • Two calls in the same minute send one e-mail.

Method POST /containers/{crid}/unlock

Scope containers:unlock

Mark the container as shipped. This does not change message visibility.

Parameters

Name In Type Required Description
crid Path string Required Your reference for the container.

Response

json 200 OK 
{"result": "ok", "shipped": true, "shippedAt": "…"}

Notes

  • Messages are published when they are encoded. Visibility does not depend on shipping.

Method GET /containers/{crid}/qrcode

Scope containers:qrcode

PNG QR code that links to the recording page of the container.

Parameters

Name In Type Required Description
crid Path string Required Your reference for the container.
size Query integer Optional Width in pixels, from 64 to 1024. Default 256.

Response

json 200 OK 
image/png

Method GET /containers/{crid}/card

Scope containers:card

Printable PDF card with the QR code and the container identifier.

Parameters

Name In Type Required Description
crid Path string Required Your reference for the container.

Response

json 200 OK 
application/pdf

Notes

  • Returns 400 NO_PDF_TEMPLATE when the platform has no PDF template, and 400 NO_LANGUAGE when no language can be resolved.
  • Returns 503 CARD_RENDERER_UNAVAILABLE or 502 CARD_RENDERER_FAILED when rendering fails.

Notifications

Set per audience. A key that is not sent keeps the value livstick. The setting decides who sends the e-mail; it has no effect on webhooks.

Name Type Default Description
notifications.organizer string livstick Who sends the e-mails to the organizer of a gallery. Values livstick client none
notifications.contributors string livstick Who sends the e-mails to the contributors of a gallery. Values livstick client none
notifications.recipient string livstick Who sends the e-mail to the recipient. client means Livstick sends nothing and your system informs the recipient, for example from the message.ready webhook. Webhooks are sent whatever the setting. Values livstick client none

States

The state field of a container.

Name Type Default Description
state string The container accepts a message. Values recording_open recording_closed