# Recipients

> The Recipients operations of the Kabu API: humans an org can reach, with consent.

Humans an org can reach, with consent.

Generated from the contract, version `2.0.0-draft.2` ([OpenAPI](/openapi.yaml)). Base URL `https://usekabu.com/api`. Errors are problem details, each [code](/docs/errors) with its own page.

## `GET /v2/recipients` · List recipients

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `recipients:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `limit` | query | integer, from 1 to 100 | no |  |
| `after` | query | string | no | Opaque cursor from next_cursor. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [RecipientList](#schema-RecipientList) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/recipients" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## `GET /v2/recipients/{recipient}` · Get a recipient

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `recipients:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `recipient` | path | string | yes | An id or slug. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [Recipient](#schema-Recipient) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/recipients/$RECIPIENT" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## `PUT /v2/recipients/{recipient}` · Create or update a recipient

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `recipients:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `recipient` | path | string | yes | An id or slug. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

**Request body**: [RecipientWrite](#schema-RecipientWrite).

| Status | Means | Body |
|---|---|---|
| `200` | OK | [Recipient](#schema-Recipient) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl -X PUT "https://usekabu.com/api/v2/recipients/$RECIPIENT" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## `DELETE /v2/recipients/{recipient}` · Delete a recipient

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `recipients:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `recipient` | path | string | yes | An id or slug. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `204` | Done |  |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl -X DELETE "https://usekabu.com/api/v2/recipients/$RECIPIENT" \
  -H "Authorization: Bearer $KABU_API_KEY"
```

## `POST /v2/recipients/{recipient}/invite` · Create a consented pairing link (app, Web Push or web)

A pairing link is a human-voice capability: a key holding messages:write gets 403 self_response_forbidden, so an agent can never pair itself as a recipient. Use a service key or a user token.

- **Auth:** an API key, or a signed-in human's token (the Kabu apps).
- **Scopes:** `recipients:write`.
- **Refused to:** a key holding `messages:write`.
- **Signed-in humans:** `admin`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `recipient` | path | string | yes | `rcp_…` or `ext:…`. |
| `Idempotency-Key` | header | string, at most 255 characters | no | Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h. |
| `Kabu-Org` | header | string | no | Select a live membership (default personal org); non-member is 404. Human tokens are live-only. Caller user id is distinct from billing owner. |

| Status | Means | Body |
|---|---|---|
| `201` | OK | [Invite](#schema-Invite) |
| `429` | A rate, concurrency or quota limit was reached | [Problem](/docs/api/discovery#schema-Problem) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl -X POST "https://usekabu.com/api/v2/recipients/$RECIPIENT/invite" \
  -H "Authorization: Bearer $KABU_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

## `GET /v2/recipient_pairings/preview` · Preview recipient pairing consent

Public capability preview for recipients.invite only; org invitation tokens are refused. No membership is created.

- **Auth:** no credentials.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `token` | query | string | yes |  |

| Status | Means | Body |
|---|---|---|
| `200` | OK | [RecipientPairingPreview](#schema-RecipientPairingPreview) |
| `429` | A rate, concurrency or quota limit was reached | [Problem](/docs/api/discovery#schema-Problem) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl "https://usekabu.com/api/v2/recipient_pairings/preview?token=%E2%80%A6"
```

## `POST /v2/recipient_pairings/accept` · Recipients pairing accept

User token and explicit consent only; consume the single-use, hashed, expiring recipient pairing token and bind its recipient to the authenticated person. No Kabu-Org or prior membership required; never creates membership. Org invitation tokens are refused. Return the consenting recipient view with settings/metadata projected to empty objects.

- **Kabu apps only:** a signed-in human's token. Integrations use API keys.
- **Signed-in humans:** `self`.

| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| `Idempotency-Key` | header | string, at most 255 characters | no | Retry-safe key. For messages, sessions and responses it binds to the created object for its life; elsewhere for 24 h. |

**Request body**: [RecipientPairingAccept](#schema-RecipientPairingAccept).

| Status | Means | Body |
|---|---|---|
| `200` | OK | [Recipient](#schema-Recipient) |
| `429` | A rate, concurrency or quota limit was reached | [Problem](/docs/api/discovery#schema-Problem) |
| `4XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |
| `5XX` | Error | [Problem](/docs/api/discovery#schema-Problem) |

```sh
curl -X POST "https://usekabu.com/api/v2/recipient_pairings/accept" \
  -H "Authorization: Bearer $KABU_USER_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"token":"…","consent":true}'
```

## Schemas

### RecipientList

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"list"` | yes |  |
| `data` | array of [Recipient](#schema-Recipient) | yes |  |
| `has_more` | boolean | yes |  |
| `next_cursor` | string or null | yes |  |

### Recipient

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"recipient"` | yes |  |
| `id` | string | yes |  |
| `external_id` | string or null | yes |  |
| `name` | string or null | yes |  |
| `email` | string or null | yes |  |
| `status` | string | yes | invited, active, unsubscribed or disabled (open). |
| `channels` | array of [Channel](/docs/api/messages#schema-Channel) | yes | Reachable now. Empty means links only. |
| `settings` | [SettingsView](/docs/api/events#schema-SettingsView) | yes | Layered: org → project → agent → recipient. Unset fields inherit. |
| `metadata` | [Metadata](/docs/api/messages#schema-Metadata) | yes | Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event. |
| `created_at` | [Timestamp](/docs/api/messages#schema-Timestamp) | yes |  |

### RecipientWrite

| Property | Type | Required | Description |
|---|---|---|---|
| `external_id` | string, at most 120 characters | no |  |
| `name` | string, at most 80 characters | no |  |
| `email` | string (email) | no |  |
| `locale` | string | no |  |
| `time_zone` | string | no |  |
| `settings` | [Settings](/docs/api/projects#schema-Settings) | no | Layered: org → project → agent → recipient. Unset fields inherit. |
| `metadata` | [Metadata](/docs/api/messages#schema-Metadata) | no | Your own key/value pairs (≤ 50 keys, values ≤ 500 chars), returned verbatim on every object and event. |

Unknown properties are refused.

### Invite

A consented pairing link to the Kabu app, Web Push or the web.

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"invite"` | yes |  |
| `url` | string (uri) | yes |  |
| `expires_at` | [Timestamp](/docs/api/messages#schema-Timestamp) | yes |  |

### RecipientPairingPreview

Capability preview only, no membership or recipient settings/metadata. Distinct from org invites.

| Property | Type | Required | Description |
|---|---|---|---|
| `object` | `"recipient_pairing"` | yes |  |
| `recipient` | string | yes |  |
| `recipient_name` | string or null | yes |  |
| `org_name` | string | yes |  |
| `expires_at` | [Timestamp](/docs/api/messages#schema-Timestamp) | yes |  |

### RecipientPairingAccept

Bind only the authenticated consenting person to the token's recipient. Explicit true consent required; no user/recipient/org/role may be supplied. Never creates membership or grants administration.

| Property | Type | Required | Description |
|---|---|---|---|
| `token` | string, 1 to 256 characters | yes |  |
| `consent` | `true` | yes |  |

Unknown properties are refused.