# Fax numbers API reference

> The number operations of the Fax for Agents API. Search inventory, order a number, route its inbound faxes, release it, port numbers in and verify a sender.

Page: https://faxforagents.com/docs/api/reference/numbers/
Last changed: 2026-11-13

Updated Nov 13, 2026

15 operations of the Fax for Agents API, from the OpenAPI document version 1.20.0, snapshot of 2026-11-13. The base URL is `https://api.faxforagents.com/v1`. This is one group of the [full reference](https://faxforagents.com/docs/api/reference/).

- A number order answers 201 with the created order even when the carrier refuses the purchase.
- Releasing a number is confirmed with the number itself, and a 30-day quarantine follows.
- A sender verification covers only a number your organization owns.

## Operations

- `GET /v1/coverage` Where we send and where we host numbers
- `GET /v1/number-inventory` Fax-capable numbers for sale
- `GET /v1/number-orders` List your number orders
- `POST /v1/number-orders` Buy a number (the first month is held now, charged on activation)
- `GET /v1/number-orders/{order_id}` Read a number order
- `GET /v1/numbers` Your numbers
- `GET /v1/numbers/{number_id}` One number
- `PATCH /v1/numbers/{number_id}` Label, inbound route and PDF by mail of a number
- `POST /v1/numbers/{number_id}/release-requests` Release a number (confirm with the number itself; 30-day quarantine follows)
- `GET /v1/port-orders` Port orders and port-out requests
- `POST /v1/port-orders` Request a port-in (handled with you)
- `GET /v1/port-orders/{port_id}` One port order
- `POST /v1/port-out-requests` Note a port-out of one of your numbers
- `POST /v1/portability-checks` Can these numbers port in
- `POST /v1/sender-verifications` Verify a number of yours as a sender (only numbers you own)

## How do I find and order a number?

Three calls. `GET /v1/coverage` says where faxes can be sent and where numbers are hosted. `GET /v1/number-inventory` lists fax-capable numbers for sale. It filters by `country`, `locality` and `type`. `POST /v1/number-orders` buys one, with the number in `e164` exactly as the inventory returned it.

The order can carry a `label`, a `project_id` under which inbound faxes are filed, and an `inbound_webhook_id`. That last field names the webhook that receives `fax.received` for this number. Without it every webhook of the organization does.

## Why does a refused order answer 201?

The OpenAPI document says it in the description of the operation. The call returns 201 with the created order, including when the carrier refuses the purchase. A refused order has status `failed` and an `error` with the carrier's reason. Its first-month hold is released and nothing is charged.

So read `status` on the answer before you use the number. The first month is held when the order is made and charged on activation. An unconfirmed carrier response leaves the order `pending` while the outcome is checked. Reusing the same `Idempotency-Key` returns the same body without another purchase, so a retry after a timeout cannot buy twice.

## What can I change on a number I own?

`GET /v1/numbers` lists your numbers, and `include_released` adds the ones you gave back. `PATCH /v1/numbers/{number_id}` changes the label, the project and the inbound route. A number shows its monthly price in `monthly_micro`, when it renews in `renews_at` and whether inbound is working in `inbound_status`.

## How is a number released?

`POST /v1/numbers/{number_id}/release-requests` gives a number back. The body has one field, `confirm`, and it takes the number itself, typed out. A 30-day quarantine follows the release. The step is deliberate: a released number stops receiving, and a fax sent to it afterwards does not reach you.

## How does porting work?

`POST /v1/portability-checks` takes a list of numbers and says which can port in. `POST /v1/port-orders` requests a port-in. The summary says "handled with you": a person on our side works through the port with you, and the order shows its `milestones` as it moves. `GET /v1/port-orders` lists port orders and port-out requests, and one can be read by id.

`POST /v1/port-out-requests` notes that one of your numbers is leaving to another carrier.

## What is a sender verification?

`POST /v1/sender-verifications` verifies one of your numbers as a sender. It takes `from`, a number your organization owns, and answers with the verification, its method and its status. A number of another organization is refused. A quote in the [quotes group](https://faxforagents.com/docs/api/reference/quotes/) names one of your numbers in `from`. Without it the fax goes out from the shared pool.

## Which scopes do number calls need?

Reads need `number:read`: coverage, inventory, orders, numbers, port orders and the portability check. Everything that buys, changes, releases or ports needs `number:buy`. The default API key does not carry `number:buy`. Choose it when you create the key, or the order answers 403. Several calls here answer 503 while the carrier is not available.

## Each operation in detail

### GET `/v1/coverage`

Where we send and where we host numbers

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Responses

GET /v1/coverage responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/coverage response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `coverage_version` | string or null | yes |  |
| `excluded` | object | yes |  |
| `generated_at` | string or null | yes |  |
| `inbound` | object | yes |  |
| `note` | string or null | yes |  |
| `orderable_now` | array of string | yes |  |
| `outbound` | object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/coverage \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/number-inventory`

Fax-capable numbers for sale

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Parameters

GET /v1/number-inventory parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `country` | query | string | no | Default `"US"` . |
| `locality` | query | string or null | no |  |
| `type` | query | string (local, toll_free) | no | Default `"local"` . |
| `limit` | query | integer | no | Default `10` . |

#### Responses

GET /v1/number-inventory responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

GET /v1/number-inventory response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes |  |
| `items` | array of object InventoryNumber | yes |  |
| `locality` | string or null | yes |  |
| `note` | string | yes |  |
| `number_type` | string | yes |  |
| `recurring_period` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/number-inventory \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/number-orders`

List your number orders

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Responses

GET /v1/number-orders responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/number-orders response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object NumberOrder | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/number-orders \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/number-orders`

Buy a number (the first month is held now, charged on activation)

Returns 201 with the created order, including when the carrier refuses the purchase. A refused order has status failed and an error describing the carrier's reason. Its first-month hold is released and nothing is charged. Reusing the same Idempotency-Key returns the same response body without another purchase. An unconfirmed carrier response leaves the order pending for reconciliation.

Credential: an API key or a signed-in session. Scope: `number:buy`.

#### Parameters

POST /v1/number-orders parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

POST /v1/number-orders request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `e164` | string | yes | A number from GET /v1/number-inventory, E.164. |
| `inbound_webhook_id` | string or null | no | The webhook that receives fax.received for this number (default: all). |
| `label` | string or null | no |  |
| `project_id` | string or null | no | Inbound faxes are filed under this project. |

#### Responses

POST /v1/number-orders responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `402` | The prepaid balance does not cover the call: insufficient_balance. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

POST /v1/number-orders response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `country` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `first_month_hold_micro` | integer | yes | Held now, captured when the number activates. |
| `id` | string | yes |  |
| `number` | object Number or null | yes |  |
| `number_id` | string or null | yes |  |
| `number_type` | string or null | yes |  |
| `provider` | string | yes |  |
| `recurring_charge_micro` | integer | yes | Charged every month on the activation day. |
| `recurring_period` | string | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/number-orders \ -X POST \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{"e164":"+15550001001"}'`
```

### GET `/v1/number-orders/{order_id}`

Read a number order

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Parameters

GET /v1/number-orders/{order_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `order_id` | path | string | yes |  |

#### Responses

GET /v1/number-orders/{order_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/number-orders/{order_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `completed_at` | string or null | yes |  |
| `country` | string or null | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string or null | yes |  |
| `environment` | string (live, test) | yes |  |
| `error` | string or null | yes |  |
| `first_month_hold_micro` | integer | yes | Held now, captured when the number activates. |
| `id` | string | yes |  |
| `number` | object Number or null | yes |  |
| `number_id` | string or null | yes |  |
| `number_type` | string or null | yes |  |
| `provider` | string | yes |  |
| `recurring_charge_micro` | integer | yes | Charged every month on the activation day. |
| `recurring_period` | string | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/number-orders/ORDER_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/numbers`

Your numbers

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Parameters

GET /v1/numbers parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `include_released` | query | boolean | no | Default `false` . |

#### Responses

GET /v1/numbers responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/numbers response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object Number | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers \ -H "Authorization: Bearer ffa_test_..."`
```

### GET `/v1/numbers/{number_id}`

One number

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Parameters

GET /v1/numbers/{number_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number_id` | path | string | yes |  |

#### Responses

GET /v1/numbers/{number_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/numbers/{number_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activated_at` | string or null | yes |  |
| `country` | string | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `email_pdf` | boolean | no | When true, the notice mail of a fax received on this number carries the PDF as an attachment. Live numbers only. Off by default. |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `inbound_status` | string | yes |  |
| `inbound_webhook_id` | string or null | yes |  |
| `label` | string or null | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `order_id` | string or null | yes |  |
| `project_id` | string or null | yes |  |
| `provider` | string | yes |  |
| `released_at` | string or null | yes |  |
| `renews_at` | string or null | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers/NUMBER_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### PATCH `/v1/numbers/{number_id}`

Label, inbound route and PDF by mail of a number

Credential: an API key or a signed-in session. Scope: `number:buy`.

#### Parameters

PATCH /v1/numbers/{number_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number_id` | path | string | yes |  |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

PATCH /v1/numbers/{number_id} request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `email_pdf` | boolean or null | no | Attach the PDF of each received fax to the notice mail. The mail goes to the verified address of an owner of the organization and to no other address. A PDF over 15 MB is not attached. It needs the scope number:buy. An agent, an OAuth connection and a connected app are refused. |
| `inbound_webhook_id` | string or null | no |  |
| `label` | string or null | no |  |
| `project_id` | string or null | no |  |

#### Responses

PATCH /v1/numbers/{number_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

PATCH /v1/numbers/{number_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activated_at` | string or null | yes |  |
| `country` | string | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `email_pdf` | boolean | no | When true, the notice mail of a fax received on this number carries the PDF as an attachment. Live numbers only. Off by default. |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `inbound_status` | string | yes |  |
| `inbound_webhook_id` | string or null | yes |  |
| `label` | string or null | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `order_id` | string or null | yes |  |
| `project_id` | string or null | yes |  |
| `provider` | string | yes |  |
| `released_at` | string or null | yes |  |
| `renews_at` | string or null | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers/NUMBER_ID \ -X PATCH \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{}'`
```

### POST `/v1/numbers/{number_id}/release-requests`

Release a number (confirm with the number itself; 30-day quarantine follows)

Credential: an API key or a signed-in session. Scope: `number:buy`.

#### Parameters

POST /v1/numbers/{number_id}/release-requests parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `number_id` | path | string | yes |  |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

POST /v1/numbers/{number_id}/release-requests request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `confirm` | string or null | no | The number itself, typed out, to confirm. |

#### Responses

POST /v1/numbers/{number_id}/release-requests responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/numbers/{number_id}/release-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `activated_at` | string or null | yes |  |
| `country` | string | yes |  |
| `created_at` | string | yes |  |
| `currency` | string | yes |  |
| `e164` | string | yes |  |
| `email_pdf` | boolean | no | When true, the notice mail of a fax received on this number carries the PDF as an attachment. Live numbers only. Off by default. |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `inbound_status` | string | yes |  |
| `inbound_webhook_id` | string or null | yes |  |
| `label` | string or null | yes |  |
| `locality` | string or null | yes |  |
| `monthly_micro` | integer | yes |  |
| `number_type` | string | yes |  |
| `order_id` | string or null | yes |  |
| `project_id` | string or null | yes |  |
| `provider` | string | yes |  |
| `released_at` | string or null | yes |  |
| `renews_at` | string or null | yes |  |
| `status` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/numbers/NUMBER_ID/release-requests \ -X POST \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{}'`
```

### GET `/v1/port-orders`

Port orders and port-out requests

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Responses

GET /v1/port-orders responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/port-orders response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object PortOrder | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-orders \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/port-orders`

Request a port-in (handled with you)

Credential: an API key or a signed-in session. Scope: `number:buy`.

#### Parameters

POST /v1/port-orders parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

POST /v1/port-orders request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string or null | no |  |
| `numbers` | array of string | yes |  |

#### Responses

POST /v1/port-orders responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/port-orders response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `direction` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `milestones` | array of object | yes |  |
| `numbers` | array of string | yes |  |
| `provider` | string | yes |  |
| `request` | object | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-orders \ -X POST \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{"numbers":["+15550001001"]}'`
```

### GET `/v1/port-orders/{port_id}`

One port order

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Parameters

GET /v1/port-orders/{port_id} parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `port_id` | path | string | yes |  |

#### Responses

GET /v1/port-orders/{port_id} responses

| Status | Meaning |
| --- | --- |
| `200` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

GET /v1/port-orders/{port_id} response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `direction` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `milestones` | array of object | yes |  |
| `numbers` | array of string | yes |  |
| `provider` | string | yes |  |
| `request` | object | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-orders/PORT_ID \ -H "Authorization: Bearer ffa_test_..."`
```

### POST `/v1/port-out-requests`

Note a port-out of one of your numbers

Credential: an API key or a signed-in session. Scope: `number:buy`.

#### Parameters

POST /v1/port-out-requests parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

POST /v1/port-out-requests request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `note` | string or null | no |  |
| `number_id` | string | yes |  |

#### Responses

POST /v1/port-out-requests responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `404` | not_found: no such resource for this credential. A resource of another organization answers the same. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/port-out-requests response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `direction` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `id` | string | yes |  |
| `milestones` | array of object | yes |  |
| `numbers` | array of string | yes |  |
| `provider` | string | yes |  |
| `request` | object | yes |  |
| `status` | string | yes |  |
| `updated_at` | string | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/port-out-requests \ -X POST \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{"number_id":"number_example"}'`
```

### POST `/v1/portability-checks`

Can these numbers port in

Credential: an API key or a signed-in session. Scope: `number:read`.

#### Parameters

POST /v1/portability-checks parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

POST /v1/portability-checks request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `numbers` | array of string | yes |  |

#### Responses

POST /v1/portability-checks responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |
| `503` | Something this call depends on is not available or not set up here, for example billing_unavailable or provider_unavailable. error.retryable says whether to send the same call again. |

#### Response fields

POST /v1/portability-checks response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checked_at` | string | yes |  |
| `items` | array of object | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/portability-checks \ -X POST \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{"numbers":["+15550001001"]}'`
```

### POST `/v1/sender-verifications`

Verify a number of yours as a sender (only numbers you own)

Credential: an API key or a signed-in session. Scope: `number:buy`.

#### Parameters

POST /v1/sender-verifications parameters

| Name | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `Idempotency-Key` | header | string | no | Replay the first successful response for the same request within 24 hours. Reusing the idempotency header with a different request returns 409 idempotency_key_conflict. Responses include Idempotent-Replayed: true on replay. |

#### Request body application/json, required

POST /v1/sender-verifications request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | yes | A number your organization owns, E.164. |

#### Responses

POST /v1/sender-verifications responses

| Status | Meaning |
| --- | --- |
| `201` | Successful Response |
| `401` | No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused. |
| `403` | The credential is valid and is not allowed to do this. scope_missing puts the scope in error.details.scope. Other codes are agent_forbidden and approval_required. A session can also meet csrf_invalid and reauth_required. |
| `409` | The resource is in a state that refuses the call, or the Idempotency-Key was used with a different request (idempotency_key_conflict). error.code names the state. |
| `422` | A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule. |
| `429` | rate_limited. Retry-After and the RateLimit-* headers say when to try again. |

#### Response fields

POST /v1/sender-verifications response fields

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string | yes |  |
| `environment` | string (live, test) | yes |  |
| `from` | string | yes |  |
| `id` | string | yes |  |
| `method` | string | yes |  |
| `number_id` | string or null | yes |  |
| `status` | string | yes |  |
| `verified_at` | string or null | yes |  |

#### Example

```
`curl https://api.faxforagents.com/v1/sender-verifications \ -X POST \ -H "Authorization: Bearer ffa_test_..." \ -H "Content-Type: application/json" \ -d '{"from":"+15550001001"}'`
```