Fax numbers API reference

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.

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 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
`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
`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
`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
`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
`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
`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"}'

Fax numbers API reference

Operations

How do I find and order a number?

Why does a refused order answer 201?

What can I change on a number I own?

How is a number released?

How does porting work?

What is a sender verification?

Which scopes do number calls need?

Each operation in detail

GET /v1/coverage

Responses

Response fields

Example

GET /v1/number-inventory

Parameters

Responses

Response fields

Example

GET /v1/number-orders

Responses

Response fields

Example

POST /v1/number-orders

Parameters

Request body application/json, required

Responses

Response fields

Example

GET /v1/number-orders/{order_id}

Parameters

Responses

Response fields

Example

GET /v1/numbers

Parameters

Responses

Response fields

Example

GET /v1/numbers/{number_id}

Parameters

Responses

Response fields

Example

PATCH /v1/numbers/{number_id}

Parameters

Request body application/json, required

Responses

Response fields

Example

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

Parameters

Request body application/json, required

Responses

Response fields

Example

GET /v1/port-orders

Responses

Response fields

Example

POST /v1/port-orders

Parameters

Request body application/json, required

Responses

Response fields

Example

GET /v1/port-orders/{port_id}

Parameters

Responses

Response fields

Example

POST /v1/port-out-requests

Parameters

Request body application/json, required

Responses

Response fields

Example

POST /v1/portability-checks

Parameters

Request body application/json, required

GET `/v1/coverage`

GET `/v1/number-inventory`

GET `/v1/number-orders`

POST `/v1/number-orders`

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

GET `/v1/numbers`

GET `/v1/numbers/{number_id}`

PATCH `/v1/numbers/{number_id}`

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

GET `/v1/port-orders`

POST `/v1/port-orders`

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

POST `/v1/port-out-requests`

POST `/v1/portability-checks`

POST `/v1/sender-verifications`