List channel pairings

Channel pairing is currently in Beta. API definitions, response structures, and behavior may change. Check the documentation for updates.

GET /api/v1/forward/channel_pairings Use Authorization: Bearer <PAT or SAT>. Only Channel pairing records accessible to the caller are returned. By default, results include pending (pairing) and bound (active) records, but exclude unbound (unbound) records.

Query parameters

Parameter	Description
`channel_id`	Optional. Specify an accessible Channel. If omitted, include all accessible Channels.
`status`	Optional: `pairing` or `active`. A Pair remains `pairing` after its pairing code expires.
`target_type`	Optional: `user` (private chat) or `group` (group chat).
`target_external_id`	Optional. Exact match on the external user or group ID. Recommended in combination with Channel and target type.
`identity_id` / `template_id`	Optional. Filter bound records only, without checking whether the Identity / Template exists. Returns an empty list when combined with `status=pairing`.
`limit`	Items per page. Default: 20. Must be an integer from 1 to 100.
`after_id` / `before_id`	Optional. Use a returned Pairing `id` as the cursor. Cannot be provided together.

Example

GET /api/v1/forward/channel_pairings?channel_id=channel_019eabc123&status=pairing&target_type=group

{
  "data": [
    {
      "id": "pair_019eabc123",
      "type": "channel_pairing",
      "channel_id": "channel_019eabc123",
      "scope_type": "room",
      "scope_external_id": "external_group_id",
      "scope_display_name": "Project discussion group",
      "status": "pairing",
      "identity_id": "",
      "template_id": "",
      "paired_at": "",
      "created_at": "2026-09-09T08:00:00Z",
      "updated_at": "2026-09-09T08:00:00Z"
    }
  ],
  "first_id": "pair_019eabc123",
  "last_id": "pair_019eabc123",
  "has_more": false
}

scope_type is direct (private chat) or room (group chat), and scope_external_id is the corresponding external user or group ID. Bound records return the actual identity_id, template_id, and paired_at. The list does not return pairing codes, employee IDs, or employee aliases, and does not generate or refresh pairing codes. If no bindings match identity_id / template_id, the API returns HTTP 200 OK with an empty list, not 404:

{"data":[],"first_id":null,"last_id":null,"has_more":false}

scope_display_name is the user's nickname or group name. It may be empty and is for display only.

HTTP error codes

HTTP	Type	Trigger
400	`invalid_request_error`	A filter value is invalid, `limit` is outside 1–100, both cursors are provided, or a parameter contains control characters.
401	`authentication_error`	PAT or SAT is invalid or expired.
403	`permission_error`	The caller does not have permission to invoke the API.
404	`not_found_error`	The specified `channel_id` does not exist or is inaccessible.

List channel pairings

Query parameters

Example

HTTP error codes

Get a channel pairing

Update a channel pairing

​Query parameters

​Example

​HTTP error codes

​Related APIs

Get a channel pairing

Update a channel pairing

Query parameters

Example

HTTP error codes

Related APIs