Create or fetch a container

Method POST https://client-api.v5.livstick.com/api/v3/containers

Use this endpoint to initialize a container by business reference (crid). Contact values can be supplied for server-side message prefill. Recipient first and last names are optional. Without recipient.channel, email is selected whenever recipient.email is available, even if a phone is also supplied. A phone-only recipient must explicitly use channel: sms. If the container already exists for the platform, the API returns existing links without mutating it. Use PATCH /containers/{crid} for corrections.

Authorization

Required scope containers:write

Use Authorization: Bearer liv_<prefix>_<secret>.

Request body

Required application/json Schema CreateContainerInput

Name	Type	Required	Description
`crid`	`string`	Required
`email`Deprecated	`string`	Optional	Deprecated alias of `sender.email`. Constraints format email
`sender`	`SenderInput`	Optional	Optional sender identity and contact values.
`recipient`	`RecipientInput`	Optional	Optional recipient identity and contact values. With no channel, email is selected when present. A phone-only recipient must set `channel` to `sms`.
`language`	`string`	Optional
`codeGroup`	`string`	Optional
`mode`	`ContainerMode`	Optional	Container mode. `single` (default) holds one message; `gallery` accepts multiple messages. Ignored when the container already exists. Values `single` `gallery`
`additionalData`	`object`	Optional	Arbitrary metadata, preserved unchanged. Historical contact aliases remain recognized: `email`, `senderEmail`, sender first/last-name variants, `receiverEmail`, `receiverPhone`, and `messageNotified`.

Responses

201 application/json Schema CreateContainerOutput

Container created or reused.

400 application/json Schema ApiErrorEnvelope

Request rejected due to invalid payload or business precondition.

json 400

{
  "error": {
    "code": "DATA_INVALID",
    "message": "Invalid request data"
  }
}

401 application/json Schema ApiErrorEnvelope

Authentication failed or missing bearer token.

json 401

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API key"
  }
}

403 application/json Schema ApiErrorEnvelope

Authenticated but not allowed by scope or key constraints.

json 403

{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions"
  }
}