> ## Documentation Index
> Fetch the complete documentation index at: https://docs.osis.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Claim a line

> POST /api/v1/comms/lines/claim — attach an available dedicated line to your account.

Attach an available dedicated iMessage/SMS line to the authenticated workspace and put it in API / webhooks inbound mode.

This endpoint is allowlisted. Accounts that are not on the list receive `403`. Checkout for everyone else comes later.

**Scope:** `comms_lines_write`

## Request

[List available numbers](/messages-api/list-available-lines) first, then pass `e164` to claim one. Omit `e164` to take the next free dedicated number.

```bash theme={null}
curl -X POST "https://osis.co/api/v1/comms/lines/claim" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```bash theme={null}
curl -X POST "https://osis.co/api/v1/comms/lines/claim" \
  -H "Authorization: Bearer $COMMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "e164": "+16285551212" }'
```

### Body parameters

<ParamField body="e164" type="string">
  Dedicated line to claim, E.164. Omit to attach the first available number.
</ParamField>

## Response

```json theme={null}
{
  "e164": "+16285551212",
  "inbound_mode": "api",
  "status": "active"
}
```

| Field          | Meaning                                     |
| -------------- | ------------------------------------------- |
| `e164`         | Number now on this account                  |
| `inbound_mode` | Always `api` after a successful claim       |
| `status`       | Line status (`active` when the claim lands) |

## Errors

| Status | Code                     | When                                            |
| ------ | ------------------------ | ----------------------------------------------- |
| `403`  | `line_claim_not_allowed` | This account cannot claim lines through the API |
| `409`  | `no_available_line`      | Inventory has no free dedicated number          |
| `409`  | `line_number_in_use`     | That number already belongs to another account  |
| `400`  | `invalid_line_number`    | `e164` is not a valid +E.164 number             |