Upsert channels

Send an array of channels. Each item creates the channel when its id does not exist, or updates it when it does. Send only the fields to change. id comes from each item and cannot be renamed here.

Requires an access token with the channels:write scope. See Token to obtain a token.

An item with only id refreshes updated_at when the channel already exists. A new id requires name and type. Omitted status defaults to ACTIVE. Omitted cms_template_id stays unset. type is stored only when the channel is created; a later request ignores it.

Request

curl -X PUT "https://firespark.cloud/api/integrations/v1/channels" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": "app", "name": "Mobile app", "type": "APP", "status": "ACTIVE" },
    { "id": "web", "name": "Website", "type": "WEB" }
  ]'

Body

An array of 1 to 100 items. Each item takes these fields:

Field	Type	Description
`id`	string	External channel id. Required. Alphanumeric characters, `_`, and `-`, 1–64 characters.
`name`	string	Display name, 1–100 characters. Letters, numbers, and single spaces.
`type`	string	Required on create. One of `APP`, `WEB`, `KIOSK`, `POS`, `CALL_CENTER`, or `AGGREGATOR`. Ignored when the channel already exists.
`cms_template_id`	string (UUID)	CMS template to link. `null` clears it.
`status`	string	`ACTIVE` or `INACTIVE`.

labels, cms, settings, attributes, uid, merchant_id, and env are ignored if sent.

Response

Zod validates the entire body before saving. If any field is invalid, HTTP 400 is returned and no items are saved. When the body is valid, items are saved one after another. HTTP 200 only when every item is saved. If a later item hits a business error, HTTP is that item’s status (422 or 500).

Field	Description
`id`	The item `id`. `null` when it was missing or invalid.
`status`	`200` when saved. `422` when `name` is already used by another channel, or a new `id` was sent without `name` and `type`. `500` for an unexpected failure.
`data`	The saved channel, including `labels` and `cms`. Only when `status` is `200`.
`error`	Error message. Only when `status` is not `200`.
`details`	Error details for item-level failures.

{
  "data": [
    {
      "id": "app",
      "status": 200,
      "data": {
        "id": "app",
        "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "merchant_id": "c1d2e3f4-a5b6-7890-cdef-123456789abc",
        "name": "Mobile app",
        "type": "APP",
        "status": "ACTIVE",
        "cms_template_id": null,
        "cms": null,
        "labels": []
      }
    },
    {
      "id": "web",
      "status": 422,
      "error": "Channel name already exists",
      "details": null
    }
  ]
}

{
  "error": "Invalid fields",
  "details": {
    "0.type": "Invalid option"
  }
}

Error responses

Status	Description
`400`	The body is not an array of 1 to 100 items, or any item has invalid fields. No items are saved.
`401`	Missing or invalid access token.
`403`	Token does not include the `channels:write` scope.

API Documentation

Endpoints

Guides

Resources

Request

Body

Response

Error responses

​Request

​Body

​Response

​Error responses

Request

Body

Response

Error responses