Skip to content
Livstick Developers
v3 Request access

Containers

The container is the object every other v3 resource hangs off. These ten operations cover its full lifecycle — create, list, read, update, resolve a URL, redirect — plus the four calls that act on a container without changing its state: notify, unlock, and the two generated assets.

API v3 — Current Base URL https://client-api.v5.livstick.com/api/v3 OpenAPI specification

Lifecycle

Creating, listing, reading, updating and resolving a container — the calls a typical integration issues most often.

Method GET /containers

Scope containers:read

List containers for the authenticated platform, newest first by default.

Parameters

Name In Type Required Description
limit Query integer Optional Maximum number of items to return. Default 50, minimum 1, maximum 200.
skip Query integer Optional Number of items to skip, for pagination. Default 0.
order Query string Optional Sort order applied to the list. Default -createdAt (newest first).

Response

json 200 OK 
{
  "items": [
    {
      "crid": "order-48210",
      "urid": "5f3e9c2b8a1d4f60",
      "state": "recording_open",
      "mode": "single"
    }
  ],
  "total": 1,
  "limit": 50,
  "skip": 0
}

Method POST /containers

Scope containers:write

Create a container, or retrieve an existing one if the crid is already taken.

Only crid is required. sender, recipient, language, codeGroup, mode and additionalData are all optional. A top-level email field is also accepted as a deprecated alias for sender.email.

Parameters

Name In Type Required Description
crid Body string Required Your own reference for the container. Reusing an existing crid does not create a second container.
sender Body object Optional firstName, lastName, email.
recipient Body object Optional firstName, lastName, email, phone, channel.
language Body string Optional Language applied to the recipient-facing surfaces generated for this container.
codeGroup Body string Optional Code group the container is created under.
mode Body string Optional single or gallery. Defaults to single. Ignored if the container already exists.
additionalData Body object Optional Free-form object, preserved as given.
email Body string Optional Deprecated alias for sender.email. Kept for backward compatibility only.

Response

json 201 Created 
{
  "crid": "order-48210",
  "urid": "5f3e9c2b8a1d4f60",
  "state": "recording_open",
  "mode": "single",
  "editKey": "ek_9f2a1c7b3e4d5f60a1b2c3d4e5f60718",
  "links": {
    "recordingUrl": "https://client-api.v5.livstick.com/r/5f3e9c2b8a1d4f60",
    "previewUrl": "https://client-api.v5.livstick.com/r/preview/5f3e9c2b8a1d4f60"
  }
}

Notes

  • editKey is returned only at creation. There is no endpoint to retrieve it afterwards — capture and store it the moment the container is created.
  • If crid already exists for the platform, the call returns that container’s current links unchanged. It never mutates an existing container, so retrying a failed request or replaying a webhook is safe by default.
  • Recipient channel selection is silent unless you read it here: without recipient.channel, email is used as soon as recipient.email is present, even if a phone number is also given. A recipient who only has a phone number must set channel: "sms" explicitly. phone follows E.164 (^\+[1-9][0-9]{7,14}$).

Method GET /containers/{crid}

Scope containers:read

Read the current state of a container and of its message.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.

Method PATCH /containers/{crid}

Scope containers:write

Correct shipment, language or contact details on an existing container.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.
shipmentCarrier Body string Optional One of chronopost, ups, coursier, dhl, other.
shipmentCode Body string Optional Carrier-specific shipment or tracking code.
newcrid Body string Optional Renames the container to a new crid.
language Body string Optional Language applied to the recipient-facing surfaces for this container.
sender Body object Optional firstName, lastName, email.
recipient Body object Optional firstName, lastName, email, phone, channel.

Method GET /containers/{crid}/url

Scope containers:read

Resolve the recording and preview URLs for a container.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.

Response

json 200 OK 
{
  "recordingUrl": "https://client-api.v5.livstick.com/r/5f3e9c2b8a1d4f60",
  "previewUrl": "https://client-api.v5.livstick.com/r/preview/5f3e9c2b8a1d4f60"
}

Method GET /containers/{crid}/redirect

Resolve a container’s destination for a direct redirect flow, without authentication.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.

Notes

  • No scope: this call takes no API key. It is strictly read-only.
  • An unknown crid returns 404.

Notify, unlock and generated assets

Four calls that act on a container in place — triggering delivery, granting recipient access, or producing a file — without moving it through the lifecycle above.

Method POST /containers/{crid}/notify

Scope containers:notify

Trigger delivery to the recipient.

The request body is optional and, when present, overrides the contact details stored on the container for this notification only.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.

Method POST /containers/{crid}/unlock

Scope containers:unlock

Make the recorded message accessible to the recipient.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.

Method GET /containers/{crid}/qrcode

Scope containers:qrcode

Generate a QR code image pointing at the container.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.

Response

json 200 OK 
image/png

Method GET /containers/{crid}/card

Scope containers:card

Generate a printable card for the container as a PDF.

Parameters

Name In Type Required Description
crid Path string Required The container’s crid.

Response

json 200 OK 
application/pdf