Skip to main content
Channels

Pair a channel

Use a pairing code or pending pairing record ID to bind an Identity and Template to a Channel message scope.

POST /api/v1/forward/channel_pairings Only applicable to Channels with identity_resolution.mode=pairing.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>
Content-TypeYesapplication/json
Idempotency-KeyNoClient-generated unique idempotency key for safe retries.

Body parameters

ParameterTypeRequiredDescription
codestringOne of twoValid pairing code displayed in the Channel message. Provide exactly one of code and channel_pairing_id.
channel_pairing_idstringOne of twoThe id returned by List channel pairings. ID-based authorization is not affected by pairing code expiration.
identity_idstringYesForward Identity ID to bind.
template_idstringYesForward Template ID to bind.

Example request

curl -s -X POST 'https://api.qoder.com/api/v1/forward/channel_pairings' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pairing-K7MP92" \
  -d '{
    "code": "K7MP92",
    "identity_id": "idn_019eabc123",
    "template_id": "tmpl_workspace_dev"
  }'
You can also pair by ID using the same endpoint and authentication: 
{
  "channel_pairing_id": "pair_019eabc123",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev"
}

Example response

HTTP 200 OK 
{
  "id": "pair_019eabc123",
  "type": "channel_pairing",
  "channel_id": "channel_019eabc123",
  "scope_type": "direct",
  "scope_external_id": "external_user_id",
  "scope_display_name": "Test user",
  "identity_id": "idn_019eabc123",
  "template_id": "tmpl_workspace_dev",
  "status": "active",
  "paired_at": "2026-07-16T10:00:00Z"
}

Response fields

FieldTypeDescription
idstringPairing ID, used for list, detail, and unpair operations. Schedule sinks reference it through channel_pairing_id.
typestringAlways channel_pairing.
channel_idstringChannel ID.
scope_typestringPairing scope: direct for a private-chat user, or room for a group chat.
scope_external_idstringExternal user or group ID for the scope.
scope_display_namestringUser nickname or group name; an empty string if unavailable. For display only, not for authorization.
identity_idstringBound Forward Identity ID.
template_idstringBound Forward Template ID.
statusstringactive on successful pairing.
paired_atstringPairing completion time.

Error codes

HTTPTypeTrigger
400invalid_request_errorThe request does not provide exactly one of code and channel_pairing_id, the code is invalid or expired, or the Channel is not in pairing mode.
401authentication_errorPAT or SAT is invalid or expired.
404not_found_errorPair, Channel, Identity, or Template does not exist or is not visible to the caller.
409conflict_errorPair is already bound to a different Identity or Template, or has been unpaired.

Notes

  • The caller must have management permissions for the corresponding Channel.
  • Rebinding the same Identity and Template succeeds. To modify an existing binding, use Update a channel pairing.
  • If the pairing code has been used but binding has not completed, retrieve the Pair ID from List channel pairings and retry.
  • Messages sent before pairing succeeds are not replayed automatically. Send them again.

Create a channel

Unpair a channel

List channel pairings

Get a channel pairing

Update a channel pairing

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference
Pair a channel - Qoder