## Link a channel

**post** `/v1/channels`

Links an Apple Messages for Business business to your brand.

**Behavior**

- Repeating a link you already hold returns HTTP 200 `already_linked`;
  idempotent, never an error.
- Never re-points an existing binding: each collision returns a distinct
  HTTP 409 naming the conflict (`brand_occupied`,
  `cross_brand_conflict`).
- Unlinking is not available through this API; contact us.

### Body Parameters

- `business_id: string`

  The business id to link, as a UUID. Anything else is `400 business_id_invalid`.

- `channel: "amb"`

  Must be `amb`; any other value is `400 channel_unsupported`.

  - `"amb"`

- `claim_token: optional string`

  The claim token authorising this link, issued to you by Linq for this
  specific business. Required to CREATE a link: without it the call is
  `400 claim_required`, and a token that does not match this brand and this
  business is `403 claim_invalid`.

  Optional rather than required because re-posting a link your brand already
  holds answers `200 already_linked` and needs no token. A claim is
  single-use, so a replay has none left to send. Omit it in that case.

  Every rejection is the same `claim_invalid` regardless of why (unknown,
  expired, already used, withdrawn, or issued for a different business), so
  the endpoint cannot be used to discover which businesses exist or who holds
  them.

### Returns

- `ChannelLinkResponse object { channel, outcome }`

  A decided link. `outcome` says whether this call created it.

  - `channel: ChannelBinding`

    One linked channel identity: the Apple Messages for Business business this
    brand receives from and sends as.

    - `business_id: string`

      The linked business id: a UUID issued at business registration.

    - `channel: "amb"`

      The messaging channel. `amb` is the only channel this API serves today.

      - `"amb"`

    - `created_at: string`

    - `entry_point_url: string`

      The Messages entry deep link for this binding
      (`https://bcrw.apple.com/urn:biz:<business_id>`); open it from an
      approved tester device to start a chat with the business and verify the
      link end to end. DERIVED from `business_id`, not stored: the URL format
      is platform knowledge, served here so no client composes it by hand.

    - `origin: "seed" or "connect" or "control"`

      Where the link came from: `connect` is a self-service link (the Connect
      landing page, or `POST /v1/channels`: the same self-service path over
      this API), `seed` is boot configuration, `control` was provisioned by
      Linq. Provenance only; all three behave identically.

      - `"seed"`

      - `"connect"`

      - `"control"`

  - `outcome: "linked" or "already_linked"`

    `linked` (status 201); this call created the binding. `already_linked`
    (status 200): your brand already held exactly this binding; nothing
    changed and nothing is wrong. The two conflicts are errors, not outcomes:
    `409 brand_occupied` (your brand already holds a DIFFERENT business id on
    the channel) and `409 cross_brand_conflict` (the business id is held by
    another brand). A link is never re-pointed by this endpoint.

    - `"linked"`

    - `"already_linked"`

### Example

```http
curl https://messages.api.linqapp.com/v1/channels \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_AMB_API_KEY" \
    -d '{
          "business_id": "a884eddf-b0ad-4be4-9c0e-071531638768",
          "channel": "amb"
        }'
```

#### Response

```json
{
  "outcome": "linked",
  "channel": {
    "channel": "amb",
    "business_id": "a884eddf-b0ad-4be4-9c0e-071531638768",
    "origin": "connect",
    "entry_point_url": "https://bcrw.apple.com/urn:biz:a884eddf-b0ad-4be4-9c0e-071531638768",
    "created_at": "2026-08-01T12:00:00Z"
  }
}
```