API v3.1

API v3.1 adds three things to v3: containers that keep their mode from creation, messages identified by a merchant reference (mrid), and signed webhooks that tell your system what happened. It is served under its own base path, and it reads and writes the same messages as the widgets, so a message recorded through the V3 widget is the same message your API lists.

Before you read this

Read the v3 authentication and containers references first. v3.1 uses the same bearer keys and the same error envelope, and the differences are described here. API keys, scopes and platform constraints

Base URL and platforms

Every v3.1 route is under the /api/v3.1 base path, on the client API host given to you at onboarding. The v3.1 base path does not share routes with /api/v3: a call to /api/v3.1/containers never reaches a v3 handler, and a v3 call never reaches a v3.1 handler.

http

https://<client-api-host>/api/v3.1/containers
Authorization: Bearer liv_<prefix>_<secret>

v3.1 serves V3 platforms only. A key whose platform is not on the V3 user app receives 403 PLATFORM_NOT_V3.
A container created through v3.1 is marked as created by the API. A container created by v3 or by the legacy stack is not visible to v3.1, and a v3.1 container is not visible to v3.
Your key must have exactly one platform constraint. A key with no constraint, or with several, receives 403 INVALID_PLATFORM_CONSTRAINTS.

Differences from v3

Most calls look the same as their v3 counterparts. These are the changes an integrator must plan for.

v3 and v3.1 compared
Topic	v3	v3.1
Base path	/api/v3	/api/v3.1
Mode of a container	Not set by the API	Required at creation (single or gallery), fixed for the life of the container
Message identity	Container and urid	Container and mrid, your own reference, unique within the container
Recording access	Edit key and recording link	Record token (rt_…) minted by your server, optionally held until payment
Viewing access	urid	View token (vt_…) minted by your server, optionally restricted to one mrid
Notifications	Sent by the notify and unlock calls	Set per audience at creation: organizer, contributors, recipient
Events	Not available	Signed webhooks, delivered at least once
Message listing	Not available	GET /containers/{crid}/messages, with fields limited by messageAccess

Every route

The table lists each v3.1 route, the scope its key needs, and the page that documents it. A route that is not in this table does not exist in v3.1.

API v3.1 routes
Method	Path	Scope	Documented in
GET	/health	none	This page
POST	/containers	containers:write	Containers
GET	/containers	containers:read	Containers
GET	/containers/{crid}	containers:read	Containers
PATCH	/containers/{crid}	containers:write	Containers
POST	/containers/{crid}/notify	containers:notify	Containers
POST	/containers/{crid}/unlock	containers:unlock	Containers
GET	/containers/{crid}/qrcode	containers:qrcode	Containers
GET	/containers/{crid}/card	containers:card	Containers
GET	/containers/{crid}/messages	messages:read	Messages and tokens
GET	/containers/{crid}/messages/{mrid}	messages:read	Messages and tokens
POST	/containers/{crid}/messages/{mrid}/release	messages:publish	Messages and tokens
DELETE	/containers/{crid}/messages/{mrid}	messages:publish	Messages and tokens
POST	/containers/{crid}/record-tokens	tokens:record	Messages and tokens
POST	/containers/{crid}/view-tokens	tokens:view	Messages and tokens
GET	/webhooks/deliveries	webhooks:read	Webhooks
GET	/docs/doc.json	none	This page

Errors

Errors use the v3 envelope: an object with a code in capitals and a message in English. Read the code, not the message text.

json

{
  "error": {
    "code": "MODE_MISMATCH",
    "message": "Container is a single-message container; a contributor token cannot be issued."
  }
}

Codes specific to v3.1
Code	Status	Meaning
PLATFORM_NOT_V3	403	The key's platform is not served by v3.1.
IMMUTABLE_FIELD	400	mode, or gallery.mode, was sent in a PATCH. The mode is fixed at creation.
CRID_IN_USE	409	The crid belongs to a container that v3.1 did not create.
MODE_MISMATCH	409	The role does not fit the container: an organizer token for a container whose main message has another mrid, or a contributor token for a single container.
GALLERY_CLOSED	409	A record token was requested for a closed gallery.
GALLERY_NOT_EMPTY	409	The main message of a gallery was deleted while other messages remain.
MESSAGE_REJECTED	409	The message was rejected by moderation and cannot be deleted through the API.
MESSAGE_MISSING	409	notify was called before any message was listed.
RATE_LIMITED	429	Too many calls for this key. Back off and retry.