## Send an invitation

**post** `/v1/invitations`

Sends a templated invitation to a phone number: the one way to start a
conversation with a customer who has not messaged you first.

**Requirements**

- `Idempotency-Key` header: required. This is business-initiated
  contact, and a blind retry must never send two.

**Behavior**

- Refusals are checked in a fixed order, most actionable first:
  validation, then idempotency, then template authorization, then
  backlog admission, then chat state, then consent.
- HTTP 429 `code` 1002 is admission control on your
  backlog, not a rate limit: your queued-but-unsent invitations plus
  this one would take longer to deliver than the delivery horizon
  allows, so the request is refused rather than queued: an invitation
  delivered hours late could go out against consent revoked in the
  meantime. `Retry-After` reflects when your backlog will actually
  clear and can legitimately be hours; retrying sooner is refused
  again. Nothing is queued and no key is recorded, so the same key
  succeeds on retry.
- A backlog refusal is checked before the chat-state and consent gates
  (validation still runs first): a recipient who has also opted out
  still fails with the consent error once there is room.

**Errors**

- HTTP 403: `invitation_card_not_granted` (your brand is no longer
  approved for the card shape the template renders), `consent_required`
- HTTP 409: `idempotency_key_reused`, `idempotency_key_processing`,
  `chat_superseded`, `chat_closed`
- HTTP 422: field-level validation; `unknown_template`;
  `field_removed` if the request still carries the retired
  `parameters` or `brand_logo_att_id` fields
- HTTP 429: `backlog_horizon_exceeded`, with `Retry-After`

### Header Parameters

- `"Idempotency-Key": string`

### Body Parameters

- `reference_id: string`

  REQUIRED correlation handle: an order number, case id or similar. Apple bounds its length and does not allow quotes. Echoed on the delivery webhooks.

- `template_id: string`

  One of YOUR invitation template ids (`invt_…`, from `POST /v1/invitation_templates`): the card's name and logo come from the template, and the platform picks the right card from whether it carries a logo. Unknown returns HTTP 422 `code` 1081.

- `to: string`

  The customer's phone number, bare E.164 (partner formatting tolerated); malformed returns HTTP 422 `code` 1071.

- `locale: optional string`

  Optional locale for the card rendering.

### Returns

- `id: string`

  Invitation id (`inv_…`).

- `chat_id: string`

  The `tel`-handled chat carrying the invitation delivery; NOT addressable for organic sends.

- `delivery: "queued"`

  - `"queued"`

- `message_id: string`

  The invitation delivery's message id; poll it via GET /v1/messages/{msg}.

- `to: string`

  The canonical `tel:+E164` handle form of the request's `to`.

### Example

```http
curl https://messages.api.linqapp.com/v1/invitations \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LINQ_AMB_API_KEY" \
    -d '{
          "reference_id": "ride-88214",
          "template_id": "invt_a4f2c718d0",
          "to": "+15555550142"
        }'
```

#### Response

```json
{
  "id": "inv_6b2e04",
  "chat_id": "chat_4f81b2",
  "message_id": "msg_2c7d90",
  "to": "tel:+15555550142",
  "delivery": "queued"
}
```