Full API reference

Updated Oct 28, 2026

Every operation of the Fax for Agents API as static HTML. 146 operations and 147 schemas from the OpenAPI document version 1.3.3, snapshot of 2026-10-30. The base URL is https://api.faxforagents.com/v1. The same document is at /openapi.json.

agents

GET /v1/agents List agent identities
POST /v1/agents Register an agent identity
GET /v1/agents/{agent_id} Read an agent with its keys and budgets
PATCH /v1/agents/{agent_id} Change an agent; disabling revokes its keys
GET /v1/agents/{agent_id}/activity The agent's audit trail
POST /v1/agents/{agent_id}/keys Mint a key for the agent (bounded scopes, secret shown once)

GET `/v1/agents`

List agent identities

Responses

GET /v1/agents responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/agents response fields
Field	Type	Required	Description
`items`	array of object Agent	yes

Example

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

POST `/v1/agents`

Request body application/json, required

POST /v1/agents request body
Field	Type	Required	Description
`contact_email`	string or null	no	Where decided approvals are mailed.
`name`	string	yes
`policy_ids`	array of string	no
`purpose`	string or null	no	Shown to humans, never evaluated.

Responses

POST /v1/agents responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/agents response fields
Field	Type	Required
`budget_id`	string or null	yes
`budgets`	array of object	yes
`contact_email`	string or null	yes
`created_at`	string	yes
`created_by`	string	yes
`disabled_at`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`keys`	array of object ApiKey	yes
`name`	string	yes
`policy_ids`	array of string	yes
`project_id`	string or null	yes
`purpose`	string or null	yes
`status`	string	yes
`updated_at`	string	yes

Example

curl https://api.faxforagents.com/v1/agents \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/agents/{agent_id}`

Read an agent with its keys and budgets

Parameters

GET /v1/agents/{agent_id} parameters
Name	In	Type	Required	Notes
`agent_id`	path	string	yes

Responses

GET /v1/agents/{agent_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/agents/{agent_id} response fields
Field	Type	Required
`budget_id`	string or null	yes
`budgets`	array of object	yes
`contact_email`	string or null	yes
`created_at`	string	yes
`created_by`	string	yes
`disabled_at`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`keys`	array of object ApiKey	yes
`name`	string	yes
`policy_ids`	array of string	yes
`project_id`	string or null	yes
`purpose`	string or null	yes
`status`	string	yes
`updated_at`	string	yes

Example

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

PATCH `/v1/agents/{agent_id}`

Change an agent; disabling revokes its keys

Parameters

PATCH /v1/agents/{agent_id} parameters
Name	In	Type	Required	Notes
`agent_id`	path	string	yes

Request body application/json, required

PATCH /v1/agents/{agent_id} request body
Field	Type	Required	Description
`contact_email`	string or null	no
`enabled`	boolean or null	no	false revokes every key of the agent.
`name`	string or null	no
`policy_ids`	array of string or null	no
`purpose`	string or null	no

Responses

PATCH /v1/agents/{agent_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/agents/{agent_id} response fields
Field	Type	Required
`budget_id`	string or null	yes
`budgets`	array of object	yes
`contact_email`	string or null	yes
`created_at`	string	yes
`created_by`	string	yes
`disabled_at`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`keys`	array of object ApiKey	yes
`name`	string	yes
`policy_ids`	array of string	yes
`project_id`	string or null	yes
`purpose`	string or null	yes
`status`	string	yes
`updated_at`	string	yes

Example

curl https://api.faxforagents.com/v1/agents/AGENT_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/agents/{agent_id}/activity`

The agent's audit trail

Parameters

GET /v1/agents/{agent_id}/activity parameters
Name	In	Type	Required	Notes
`agent_id`	path	string	yes
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/agents/{agent_id}/activity responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/agents/{agent_id}/activity response fields
Field	Type	Required	Description
`items`	array of object AgentActivity	yes
`next_cursor`	string or null	no

Example

curl https://api.faxforagents.com/v1/agents/AGENT_ID/activity \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/agents/{agent_id}/keys`

Mint a key for the agent (bounded scopes, secret shown once)

Parameters

POST /v1/agents/{agent_id}/keys parameters
Name	In	Type	Required	Notes
`agent_id`	path	string	yes

Request body application/json, required

POST /v1/agents/{agent_id}/keys request body
Field	Type	Required	Description
`environment`	string (live, test)	no
`expires_in_days`	integer or null	no
`label`	string	no
`scopes`	array of string or null	no	Omit for the default agent set. Never approval:decide, key:admin, policy:admin, agent:admin.

Responses

POST /v1/agents/{agent_id}/keys responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/agents/{agent_id}/keys response fields
Field	Type	Required	Description
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`id`	string	yes
`label`	string	yes
`last_used_at`	string or null	yes
`prefix`	string	yes
`project_id`	string or null	yes
`revoked_at`	string or null	yes
`rotated_from_id`	string or null	yes
`scopes`	array of string	yes
`secret`	string	yes	Shown once. Store it now; it cannot be read back.

Example

curl https://api.faxforagents.com/v1/agents/AGENT_ID/keys \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

identity

GET /v1/api-keys List API keys (metadata only)
POST /v1/api-keys Create an API key (the secret is shown once)
DELETE /v1/api-keys/{key_id} Revoke a key
POST /v1/api-keys/{key_id}/rotate Rotate a key: a new secret, the old one works for 24 more hours
GET /v1/me Who am I

GET `/v1/api-keys`

List API keys (metadata only)

Responses

GET /v1/api-keys responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/api-keys response fields
Field	Type	Required	Description
`items`	array of object ApiKey	yes

Example

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

POST `/v1/api-keys`

Create an API key (the secret is shown once)

Request body application/json, required

POST /v1/api-keys request body
Field	Type	Required	Description
`environment`	string (live, test)	no
`expires_in_days`	integer or null	no
`label`	string	yes
`scopes`	array of string or null	no	Omit for the default agent set; '*' for all.

Responses

POST /v1/api-keys responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/api-keys response fields
Field	Type	Required	Description
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`id`	string	yes
`label`	string	yes
`last_used_at`	string or null	yes
`prefix`	string	yes
`project_id`	string or null	yes
`revoked_at`	string or null	yes
`rotated_from_id`	string or null	yes
`scopes`	array of string	yes
`secret`	string	yes	Shown once. Store it now; it cannot be read back.

Example

curl https://api.faxforagents.com/v1/api-keys \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/api-keys/{key_id}`

Revoke a key

Parameters

DELETE /v1/api-keys/{key_id} parameters
Name	In	Type	Required	Notes
`key_id`	path	string	yes

Responses

DELETE /v1/api-keys/{key_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

DELETE /v1/api-keys/{key_id} response fields
Field	Type	Required	Description
`deleted`	boolean	no
`id`	string	yes

Example

curl https://api.faxforagents.com/v1/api-keys/KEY_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/api-keys/{key_id}/rotate`

Rotate a key: a new secret, the old one works for 24 more hours

Parameters

POST /v1/api-keys/{key_id}/rotate parameters
Name	In	Type	Required	Notes
`key_id`	path	string	yes

Responses

POST /v1/api-keys/{key_id}/rotate responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/api-keys/{key_id}/rotate response fields
Field	Type	Required	Description
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`id`	string	yes
`label`	string	yes
`last_used_at`	string or null	yes
`prefix`	string	yes
`project_id`	string or null	yes
`revoked_at`	string or null	yes
`rotated_from_id`	string or null	yes
`scopes`	array of string	yes
`secret`	string	yes	Shown once. Store it now; it cannot be read back.

Example

curl https://api.faxforagents.com/v1/api-keys/KEY_ID/rotate \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/me`

Who am I

Responses

GET /v1/me responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/me response fields
Field	Type	Required
`actor`	string	yes
`environment`	string (live, test)	yes
`key_id`	string	yes
`key_prefix`	string	yes
`org_id`	string	yes
`project_id`	string	yes
`scopes`	array of string	yes

Example

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

approvals

GET /v1/approval-requests Approval requests, pending first
POST /v1/approval-requests Ask a human to approve a quoted send, or ask for help (grants nothing)
GET /v1/approval-requests/{approval_id} Read one request
POST /v1/approval-requests/{approval_id}/approve Approve the bound quote (a human with approval:decide, never the requester)
POST /v1/approval-requests/{approval_id}/reject Reject with a reason
POST /v1/approvals/{approval_id}/revoke Revoke an approval nobody has used yet

GET `/v1/approval-requests`

Approval requests, pending first

Parameters

GET /v1/approval-requests parameters
Name	In	Type	Required	Notes
`status`	query	string or null	no
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/approval-requests responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/approval-requests response fields
Field	Type	Required	Description
`items`	array of object ApprovalRequest	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/approval-requests`

Ask a human to approve a quoted send, or ask for help (grants nothing)

Request body application/json, required

POST /v1/approval-requests request body
Field	Type	Required	Description
`fax_job_id`	string or null	no
`kind`	string (send, help)	no
`message`	string or null	no	What the person should know (kind help). Shown as data.
`quote_id`	string or null	no	The quote to bind (kind send).

Responses

POST /v1/approval-requests responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/approval-requests response fields
Field	Type	Required	Description
`bound`	object	yes
`consumed_by_job_id`	string or null	yes
`created_at`	string	yes
`decided_at`	string or null	yes
`decided_by`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (send, help)	yes
`message`	string or null	yes
`notified`	boolean or null	no	On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard.
`quote_id`	string or null	yes
`reason`	string or null	yes
`requested_by`	string	yes
`status`	string (pending, approved, rejected, revoked, expired)	yes

Example

curl https://api.faxforagents.com/v1/approval-requests \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/approval-requests/{approval_id}`

Read one request

Parameters

GET /v1/approval-requests/{approval_id} parameters
Name	In	Type	Required	Notes
`approval_id`	path	string	yes

Responses

GET /v1/approval-requests/{approval_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/approval-requests/{approval_id} response fields
Field	Type	Required	Description
`bound`	object	yes
`consumed_by_job_id`	string or null	yes
`created_at`	string	yes
`decided_at`	string or null	yes
`decided_by`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (send, help)	yes
`message`	string or null	yes
`notified`	boolean or null	no	On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard.
`quote_id`	string or null	yes
`reason`	string or null	yes
`requested_by`	string	yes
`status`	string (pending, approved, rejected, revoked, expired)	yes

Example

curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/approval-requests/{approval_id}/approve`

Approve the bound quote (a human with approval:decide, never the requester)

Parameters

POST /v1/approval-requests/{approval_id}/approve parameters
Name	In	Type	Required	Notes
`approval_id`	path	string	yes

Request body application/json, required

POST /v1/approval-requests/{approval_id}/approve request body
Field	Type	Required	Description
`reason`	string or null	no

Responses

POST /v1/approval-requests/{approval_id}/approve responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/approval-requests/{approval_id}/approve response fields
Field	Type	Required	Description
`bound`	object	yes
`consumed_by_job_id`	string or null	yes
`created_at`	string	yes
`decided_at`	string or null	yes
`decided_by`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (send, help)	yes
`message`	string or null	yes
`notified`	boolean or null	no	On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard.
`quote_id`	string or null	yes
`reason`	string or null	yes
`requested_by`	string	yes
`status`	string (pending, approved, rejected, revoked, expired)	yes

Example

curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID/approve \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/approval-requests/{approval_id}/reject`

Reject with a reason

Parameters

POST /v1/approval-requests/{approval_id}/reject parameters
Name	In	Type	Required	Notes
`approval_id`	path	string	yes

Request body application/json, required

POST /v1/approval-requests/{approval_id}/reject request body
Field	Type	Required	Description
`reason`	string or null	no

Responses

POST /v1/approval-requests/{approval_id}/reject responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/approval-requests/{approval_id}/reject response fields
Field	Type	Required	Description
`bound`	object	yes
`consumed_by_job_id`	string or null	yes
`created_at`	string	yes
`decided_at`	string or null	yes
`decided_by`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (send, help)	yes
`message`	string or null	yes
`notified`	boolean or null	no	On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard.
`quote_id`	string or null	yes
`reason`	string or null	yes
`requested_by`	string	yes
`status`	string (pending, approved, rejected, revoked, expired)	yes

Example

curl https://api.faxforagents.com/v1/approval-requests/APPROVAL_ID/reject \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/approvals/{approval_id}/revoke`

Revoke an approval nobody has used yet

Parameters

POST /v1/approvals/{approval_id}/revoke parameters
Name	In	Type	Required	Notes
`approval_id`	path	string	yes

Request body application/json, required

POST /v1/approvals/{approval_id}/revoke request body
Field	Type	Required	Description
`reason`	string or null	no

Responses

POST /v1/approvals/{approval_id}/revoke responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/approvals/{approval_id}/revoke response fields
Field	Type	Required	Description
`bound`	object	yes
`consumed_by_job_id`	string or null	yes
`created_at`	string	yes
`decided_at`	string or null	yes
`decided_by`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (send, help)	yes
`message`	string or null	yes
`notified`	boolean or null	no	On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard.
`quote_id`	string or null	yes
`reason`	string or null	yes
`requested_by`	string	yes
`status`	string (pending, approved, rejected, revoked, expired)	yes

Example

curl https://api.faxforagents.com/v1/approvals/APPROVAL_ID/revoke \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

auth

POST /v1/auth/invitations/{token}/accept Join the organization an invitation link names (the signed-in email must match)
POST /v1/auth/logout End this session
POST /v1/auth/magic-links Send a sign-in link to an email address (always 202)
GET /v1/auth/magic-links/{token} Open a sign-in link: sets the session cookie and redirects to the app
GET /v1/auth/me The signed-in person, their organizations and the CSRF token
GET /v1/auth/oauth/{provider}/callback Finish GitHub or Google sign-in (the app forwards its /auth/{provider}/callback here)
GET /v1/auth/oauth/{provider}/start Begin GitHub or Google sign-in (redirects to the provider)
GET /v1/auth/passkeys Your passkeys
POST /v1/auth/passkeys/login/options Options for navigator.credentials.get() (discoverable, no email needed)
POST /v1/auth/passkeys/login/verify Sign in with a passkey assertion
POST /v1/auth/passkeys/register/options Options for navigator.credentials.create() (fresh session required)
POST /v1/auth/passkeys/register/verify Store a new passkey after the browser created it
DELETE /v1/auth/passkeys/{passkey_id} Remove one of your passkeys
GET /v1/auth/providers Which sign-in methods are available
POST /v1/auth/reauth Prove it is you again (passkey now, or a fresh link by mail) before a sensitive action
DELETE /v1/auth/sessions Sign out everywhere else
GET /v1/auth/sessions Your live sessions
DELETE /v1/auth/sessions/{session_id} Revoke one of your sessions
POST /v1/auth/switch-organization Look at another organization you belong to

POST `/v1/auth/invitations/{token}/accept`

Join the organization an invitation link names (the signed-in email must match)

Parameters

POST /v1/auth/invitations/{token}/accept parameters
Name	In	Type	Required	Notes
`token`	path	string	yes

Responses

POST /v1/auth/invitations/{token}/accept responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/auth/invitations/{token}/accept response fields
Field	Type	Required	Description
`organization`	object OrganizationSummary	yes

Example

curl https://api.faxforagents.com/v1/auth/invitations/TOKEN/accept \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/auth/logout`

End this session

Responses

POST /v1/auth/logout responses
Status	Meaning
`204`	Successful Response

Example

curl https://api.faxforagents.com/v1/auth/logout \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/auth/magic-links`

Send a sign-in link to an email address (always 202)

Request body application/json, required

POST /v1/auth/magic-links request body
Field	Type	Required	Description
`email`	string (email)	yes
`next`	string or null	no	An in-app path to open after sign-in.

Responses

POST /v1/auth/magic-links responses
Status	Meaning
`202`	Successful Response
`422`	Validation Error

Response fields

POST /v1/auth/magic-links response fields
Field	Type	Required	Description
`message`	string	yes
`sent`	boolean	yes

Example

curl https://api.faxforagents.com/v1/auth/magic-links \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/auth/magic-links/{token}`

Open a sign-in link: sets the session cookie and redirects to the app

Parameters

GET /v1/auth/magic-links/{token} parameters
Name	In	Type	Required	Notes
`token`	path	string	yes

Responses

GET /v1/auth/magic-links/{token} responses
Status	Meaning
`303`	Redirect to the app, signed in or with an error code in the query.
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/auth/magic-links/TOKEN \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/auth/me`

The signed-in person, their organizations and the CSRF token

Responses

GET /v1/auth/me responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/auth/me response fields
Field	Type	Required
`csrf_token`	string	yes
`organization`	object OrganizationSummary or null	yes
`organizations`	array of object OrganizationSummary	yes
`passkeys`	integer	yes
`providers`	object Providers	yes
`session`	object SessionInfo	yes
`user`	object UserOut	yes

Example

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

GET `/v1/auth/oauth/{provider}/callback`

Finish GitHub or Google sign-in (the app forwards its /auth/{provider}/callback here)

Parameters

GET /v1/auth/oauth/{provider}/callback parameters
Name	In	Type	Required	Notes
`provider`	path	string	yes
`code`	query	string	no	Default `""`.
`state`	query	string	no	Default `""`.
`error`	query	string or null	no

Responses

GET /v1/auth/oauth/{provider}/callback responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/auth/oauth/{provider}/callback response fields
Field	Type	Required
`csrf_token`	string	yes
`organization`	object OrganizationSummary or null	yes
`organizations`	array of object OrganizationSummary	yes
`passkeys`	integer	yes
`providers`	object Providers	yes
`session`	object SessionInfo	yes
`user`	object UserOut	yes

Example

curl https://api.faxforagents.com/v1/auth/oauth/PROVIDER/callback \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/auth/oauth/{provider}/start`

Begin GitHub or Google sign-in (redirects to the provider)

Parameters

GET /v1/auth/oauth/{provider}/start parameters
Name	In	Type	Required	Notes
`provider`	path	string	yes
`next`	query	string or null	no

Responses

GET /v1/auth/oauth/{provider}/start responses
Status	Meaning
`303`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/auth/oauth/PROVIDER/start \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/auth/passkeys`

Your passkeys

Responses

GET /v1/auth/passkeys responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/auth/passkeys response fields
Field	Type	Required	Description
`items`	array of object Passkey	yes

Example

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

POST `/v1/auth/passkeys/login/options`

Options for navigator.credentials.get() (discoverable, no email needed)

Responses

POST /v1/auth/passkeys/login/options responses
Status	Meaning
`200`	Successful Response

Example

curl https://api.faxforagents.com/v1/auth/passkeys/login/options \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/auth/passkeys/login/verify`

Request body application/json, required

POST /v1/auth/passkeys/login/verify request body
Field	Type	Required	Description
`credential`	object	yes

Responses

POST /v1/auth/passkeys/login/verify responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/auth/passkeys/login/verify response fields
Field	Type	Required
`csrf_token`	string	yes
`organization`	object OrganizationSummary or null	yes
`organizations`	array of object OrganizationSummary	yes
`passkeys`	integer	yes
`providers`	object Providers	yes
`session`	object SessionInfo	yes
`user`	object UserOut	yes

Example

curl https://api.faxforagents.com/v1/auth/passkeys/login/verify \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/auth/passkeys/register/options`

Options for navigator.credentials.create() (fresh session required)

Responses

POST /v1/auth/passkeys/register/options responses
Status	Meaning
`200`	Successful Response

Example

curl https://api.faxforagents.com/v1/auth/passkeys/register/options \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/auth/passkeys/register/verify`

Store a new passkey after the browser created it

Request body application/json, required

POST /v1/auth/passkeys/register/verify request body
Field	Type	Required	Description
`credential`	object	yes
`label`	string or null	no

Responses

POST /v1/auth/passkeys/register/verify responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/auth/passkeys/register/verify response fields
Field	Type	Required
`aaguid`	string or null	yes
`backup_eligible`	boolean	yes
`created_at`	string	yes
`id`	string	yes
`label`	string or null	yes
`last_used_at`	string or null	yes
`transports`	array of string or null	yes

Example

curl https://api.faxforagents.com/v1/auth/passkeys/register/verify \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/auth/passkeys/{passkey_id}`

Remove one of your passkeys

Parameters

DELETE /v1/auth/passkeys/{passkey_id} parameters
Name	In	Type	Required	Notes
`passkey_id`	path	string	yes

Responses

DELETE /v1/auth/passkeys/{passkey_id} responses
Status	Meaning
`204`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/auth/passkeys/PASSKEY_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/auth/providers`

Which sign-in methods are available

Responses

GET /v1/auth/providers responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/auth/providers response fields
Field	Type	Required
`github`	boolean	yes
`google`	boolean	yes
`magic_link`	boolean	no
`passkeys`	boolean	no

Example

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

POST `/v1/auth/reauth`

Prove it is you again (passkey now, or a fresh link by mail) before a sensitive action

Request body application/json, required

POST /v1/auth/reauth request body
Field	Type	Required	Description
`credential`	object or null	no
`method`	string (passkey, magic_link)	yes

Responses

POST /v1/auth/reauth responses
Status	Meaning
`200`	Successful Response
`202`	A sign-in link was sent; opening it in this browser refreshes the session.
`422`	Validation Error

Response fields

POST /v1/auth/reauth response fields
Field	Type	Required
`csrf_token`	string	yes
`organization`	object OrganizationSummary or null	yes
`organizations`	array of object OrganizationSummary	yes
`passkeys`	integer	yes
`providers`	object Providers	yes
`session`	object SessionInfo	yes
`user`	object UserOut	yes

Example

curl https://api.faxforagents.com/v1/auth/reauth \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/auth/sessions`

Sign out everywhere else

Responses

DELETE /v1/auth/sessions responses
Status	Meaning
`200`	Successful Response

Response fields

DELETE /v1/auth/sessions response fields
Field	Type	Required	Description
`revoked`	integer	yes

Example

curl https://api.faxforagents.com/v1/auth/sessions \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/auth/sessions`

Your live sessions

Responses

GET /v1/auth/sessions responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/auth/sessions response fields
Field	Type	Required	Description
`items`	array of object SessionOut	yes

Example

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

DELETE `/v1/auth/sessions/{session_id}`

Revoke one of your sessions

Parameters

DELETE /v1/auth/sessions/{session_id} parameters
Name	In	Type	Required	Notes
`session_id`	path	string	yes

Responses

DELETE /v1/auth/sessions/{session_id} responses
Status	Meaning
`204`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/auth/sessions/SESSION_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/auth/switch-organization`

Look at another organization you belong to

Request body application/json, required

POST /v1/auth/switch-organization request body
Field	Type	Required	Description
`org_id`	string	yes

Responses

POST /v1/auth/switch-organization responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/auth/switch-organization response fields
Field	Type	Required
`csrf_token`	string	yes
`organization`	object OrganizationSummary or null	yes
`organizations`	array of object OrganizationSummary	yes
`passkeys`	integer	yes
`providers`	object Providers	yes
`session`	object SessionInfo	yes
`user`	object UserOut	yes

Example

curl https://api.faxforagents.com/v1/auth/switch-organization \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

billing

GET /v1/auto-topups Auto top-up settings
POST /v1/auto-topups Opt in to auto top-up (threshold, amount, daily cap); the card is saved at the first payment
DELETE /v1/auto-topups/{auto_topup_id} Turn auto top-up off
GET /v1/balance Available and held balance
POST /v1/billing-portal-sessions Open the Stripe customer portal (cards, invoices, the subscription)
GET /v1/billing-settings Billing settings of the organization
PATCH /v1/billing-settings Change the billing email or the low-balance threshold
GET /v1/budgets Spending caps of this environment
POST /v1/budgets Create a daily or monthly cap for the organization, a project or an agent
PATCH /v1/budgets/{budget_id} Change a cap's limit or status
GET /v1/invoices Stripe invoices and receipts (hosted links)
GET /v1/invoices/{invoice_id} One Stripe invoice
GET /v1/ledger Wallet transactions, newest first
GET /v1/subscriptions Subscriptions and the workspace entitlement
POST /v1/subscriptions/checkout Open a hosted Checkout for the Agent workspace subscription
GET /v1/topup-sessions Top-up sessions, newest first
POST /v1/topup-sessions Open a hosted Checkout to fund the live wallet (10 to 1000 USD)
GET /v1/topup-sessions/{topup_session_id} Read a top-up session
GET /v1/usage Usage rollups by day, direction, destination and project
POST /v1/usage-exports Export usage as CSV behind a signed download
GET /v1/usage-exports/{export_id} Read a usage export (fresh link)
GET /v1/usage-exports/{export_id}/content The CSV behind a signed URL (no API key)

GET `/v1/auto-topups`

Auto top-up settings

Responses

GET /v1/auto-topups responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/auto-topups response fields
Field	Type	Required	Description
`items`	array of object AutoTopup	yes

Example

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

POST `/v1/auto-topups`

Opt in to auto top-up (threshold, amount, daily cap); the card is saved at the first payment

Request body application/json, required

POST /v1/auto-topups request body
Field	Type	Required	Description
`amount_micro`	integer	yes	Whole dollars, 10 to 1000 USD.
`daily_cap_micro`	integer	yes	Never more than this per UTC day.
`threshold_micro`	integer	yes	Top up when the available balance drops below this.

Responses

POST /v1/auto-topups responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/auto-topups response fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`created_at`	string	yes
`daily_cap_micro`	integer	yes
`disabled_at`	string or null	yes
`environment`	string (live, test)	yes
`id`	string	yes
`last_attempt_at`	string or null	yes
`payment_method_saved`	boolean	yes
`setup_session_id`	string or null	yes
`setup_url`	string or null	no	Where to save the card while status is pending_setup.
`status`	string (pending_setup, active, disabled)	yes
`threshold_micro`	integer	yes
`updated_at`	string	yes

Example

curl https://api.faxforagents.com/v1/auto-topups \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/auto-topups/{auto_topup_id}`

Turn auto top-up off

Parameters

DELETE /v1/auto-topups/{auto_topup_id} parameters
Name	In	Type	Required	Notes
`auto_topup_id`	path	string	yes

Responses

DELETE /v1/auto-topups/{auto_topup_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

DELETE /v1/auto-topups/{auto_topup_id} response fields
Field	Type	Required	Description
`deleted`	boolean	no
`id`	string	yes

Example

curl https://api.faxforagents.com/v1/auto-topups/AUTO_TOPUP_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/balance`

Available and held balance

Responses

GET /v1/balance responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/balance response fields
Field	Type	Required
`available_micro`	integer	yes
`currency`	string	yes
`environment`	string (live, test)	yes
`held_micro`	integer	yes

Example

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

POST `/v1/billing-portal-sessions`

Open the Stripe customer portal (cards, invoices, the subscription)

Responses

POST /v1/billing-portal-sessions responses
Status	Meaning
`201`	Successful Response

Response fields

POST /v1/billing-portal-sessions response fields
Field	Type	Required	Description
`expires_at`	string	yes
`url`	string	yes

Example

curl https://api.faxforagents.com/v1/billing-portal-sessions \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/billing-settings`

Billing settings of the organization

Responses

GET /v1/billing-settings responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/billing-settings response fields
Field	Type	Required
`billing_email`	string or null	yes
`disputed`	boolean	yes
`low_balance_active`	boolean	yes
`low_balance_threshold_micro`	integer	yes
`org_id`	string	yes
`stripe_customer`	boolean	yes
`workspace`	boolean	yes

Example

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

PATCH `/v1/billing-settings`

Change the billing email or the low-balance threshold

Request body application/json, required

PATCH /v1/billing-settings request body
Field	Type	Required	Description
`billing_email`	string or null	no
`low_balance_threshold_micro`	integer or null	no

Responses

PATCH /v1/billing-settings responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/billing-settings response fields
Field	Type	Required
`billing_email`	string or null	yes
`disputed`	boolean	yes
`low_balance_active`	boolean	yes
`low_balance_threshold_micro`	integer	yes
`org_id`	string	yes
`stripe_customer`	boolean	yes
`workspace`	boolean	yes

Example

curl https://api.faxforagents.com/v1/billing-settings \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/budgets`

Spending caps of this environment

Responses

GET /v1/budgets responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/budgets response fields
Field	Type	Required	Description
`items`	array of object Budget	yes

Example

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

POST `/v1/budgets`

Create a daily or monthly cap for the organization, a project or an agent

Request body application/json, required

POST /v1/budgets request body
Field	Type	Required
`agent_id`	string or null	no
`limit_micro`	integer	yes
`period`	string (daily, monthly)	yes
`project_id`	string or null	no
`scope`	string (organization, project, agent)	no

Responses

POST /v1/budgets responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/budgets response fields
Field	Type	Required
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`id`	string	yes
`limit_micro`	integer	yes
`period`	string (daily, monthly)	yes
`project_id`	string or null	yes
`remaining_micro`	integer	yes
`resets_at`	string	yes
`scope`	string (organization, project, agent)	yes
`spent_micro`	integer	yes
`status`	string (active, disabled)	yes
`updated_at`	string	yes

Example

curl https://api.faxforagents.com/v1/budgets \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

PATCH `/v1/budgets/{budget_id}`

Change a cap's limit or status

Parameters

PATCH /v1/budgets/{budget_id} parameters
Name	In	Type	Required	Notes
`budget_id`	path	string	yes

Request body application/json, required

PATCH /v1/budgets/{budget_id} request body
Field	Type	Required	Description
`limit_micro`	integer or null	no
`status`	string (active, disabled) or null	no

Responses

PATCH /v1/budgets/{budget_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/budgets/{budget_id} response fields
Field	Type	Required
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`id`	string	yes
`limit_micro`	integer	yes
`period`	string (daily, monthly)	yes
`project_id`	string or null	yes
`remaining_micro`	integer	yes
`resets_at`	string	yes
`scope`	string (organization, project, agent)	yes
`spent_micro`	integer	yes
`status`	string (active, disabled)	yes
`updated_at`	string	yes

Example

curl https://api.faxforagents.com/v1/budgets/BUDGET_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/invoices`

Stripe invoices and receipts (hosted links)

Parameters

GET /v1/invoices parameters
Name	In	Type	Required	Notes
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `20`.

Responses

GET /v1/invoices responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/invoices response fields
Field	Type	Required	Description
`items`	array of object Invoice	yes
`next_cursor`	string or null	no

Example

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

GET `/v1/invoices/{invoice_id}`

One Stripe invoice

Parameters

GET /v1/invoices/{invoice_id} parameters
Name	In	Type	Required	Notes
`invoice_id`	path	string	yes

Responses

GET /v1/invoices/{invoice_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/invoices/{invoice_id} response fields
Field	Type	Required
`amount_due_micro`	integer	yes
`amount_paid_micro`	integer	yes
`created_at`	string or null	yes
`currency`	string	yes
`hosted_invoice_url`	string or null	yes
`id`	string	yes
`invoice_pdf`	string or null	yes
`number`	string or null	yes
`status`	string or null	yes
`subscription_id`	string or null	yes

Example

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

GET `/v1/ledger`

Wallet transactions, newest first

Parameters

GET /v1/ledger parameters
Name	In	Type	Required	Notes
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/ledger responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/ledger response fields
Field	Type	Required	Description
`items`	array of object LedgerEntry	yes
`next_cursor`	string or null	no

Example

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

GET `/v1/subscriptions`

Subscriptions and the workspace entitlement

Responses

GET /v1/subscriptions responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/subscriptions response fields
Field	Type	Required
`items`	array of object Subscription	yes
`next_cursor`	string or null	no
`workspace`	boolean	yes

Example

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

POST `/v1/subscriptions/checkout`

Open a hosted Checkout for the Agent workspace subscription

Responses

POST /v1/subscriptions/checkout responses
Status	Meaning
`201`	Successful Response

Response fields

POST /v1/subscriptions/checkout response fields
Field	Type	Required
`product`	string	yes
`stripe_session_id`	string	yes
`url`	string	yes

Example

curl https://api.faxforagents.com/v1/subscriptions/checkout \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/topup-sessions`

Top-up sessions, newest first

Parameters

GET /v1/topup-sessions parameters
Name	In	Type	Required	Notes
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/topup-sessions responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/topup-sessions response fields
Field	Type	Required	Description
`items`	array of object TopupSession	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/topup-sessions`

Open a hosted Checkout to fund the live wallet (10 to 1000 USD)

Request body application/json, required

POST /v1/topup-sessions request body
Field	Type	Required	Description
`amount_usd`	integer	yes	Whole US dollars, 10 to 1000 per session.

Responses

POST /v1/topup-sessions responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/topup-sessions response fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`auto_topup_id`	string or null	yes
`completed_at`	string or null	yes
`created_at`	string	yes
`currency`	string	yes
`environment`	string (live, test)	yes
`error`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (manual, auto, setup)	yes
`status`	string (open, completed, expired, canceled, failed)	yes
`stripe_payment_intent_id`	string or null	yes
`stripe_session_id`	string or null	yes
`url`	string or null	no	The hosted Checkout page while the session is open.

Example

curl https://api.faxforagents.com/v1/topup-sessions \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/topup-sessions/{topup_session_id}`

Read a top-up session

Parameters

GET /v1/topup-sessions/{topup_session_id} parameters
Name	In	Type	Required	Notes
`topup_session_id`	path	string	yes

Responses

GET /v1/topup-sessions/{topup_session_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/topup-sessions/{topup_session_id} response fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`auto_topup_id`	string or null	yes
`completed_at`	string or null	yes
`created_at`	string	yes
`currency`	string	yes
`environment`	string (live, test)	yes
`error`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (manual, auto, setup)	yes
`status`	string (open, completed, expired, canceled, failed)	yes
`stripe_payment_intent_id`	string or null	yes
`stripe_session_id`	string or null	yes
`url`	string or null	no	The hosted Checkout page while the session is open.

Example

curl https://api.faxforagents.com/v1/topup-sessions/TOPUP_SESSION_ID \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/usage`

Usage rollups by day, direction, destination and project

Parameters

GET /v1/usage parameters
Name	In	Type	Required	Notes
`from`	query	string or null	no
`to`	query	string or null	no
`group_by`	query	string	no	Comma-separated subset. Default `"day,direction,route,project"`.
`project_id`	query	string or null	no

Responses

GET /v1/usage responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/usage response fields
Field	Type	Required
`currency`	string	yes
`environment`	string (live, test)	yes
`from`	string	yes
`group_by`	array of string	yes
`items`	array of object UsageItem	yes
`to`	string	yes
`totals`	object	yes

Example

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

POST `/v1/usage-exports`

Export usage as CSV behind a signed download

Request body application/json, required

POST /v1/usage-exports request body
Field	Type	Required	Description
`from`	string or null	no	ISO date; default 30 days ago.
`to`	string or null	no	ISO date; default today.

Responses

POST /v1/usage-exports responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/usage-exports response fields
Field	Type	Required
`content_type`	string	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string	yes
`id`	string	yes
`params`	object	yes
`row_count`	integer	yes
`status`	string (ready, expired)	yes
`url`	string or null	yes

Example

curl https://api.faxforagents.com/v1/usage-exports \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/usage-exports/{export_id}`

Read a usage export (fresh link)

Parameters

GET /v1/usage-exports/{export_id} parameters
Name	In	Type	Required	Notes
`export_id`	path	string	yes

Responses

GET /v1/usage-exports/{export_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/usage-exports/{export_id} response fields
Field	Type	Required
`content_type`	string	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string	yes
`id`	string	yes
`params`	object	yes
`row_count`	integer	yes
`status`	string (ready, expired)	yes
`url`	string or null	yes

Example

curl https://api.faxforagents.com/v1/usage-exports/EXPORT_ID \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/usage-exports/{export_id}/content`

The CSV behind a signed URL (no API key)

Parameters

GET /v1/usage-exports/{export_id}/content parameters
Name	In	Type	Required
`export_id`	path	string	yes
`exp`	query	string or null	no
`sig`	query	string or null	no

Responses

GET /v1/usage-exports/{export_id}/content responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/usage-exports/EXPORT_ID/content \
  -H "Authorization: Bearer ffa_test_..."

platform

GET /v1/capabilities Limits and features in force
GET /v1/service-status Customer-safe availability

GET `/v1/capabilities`

Limits and features in force

Responses

GET /v1/capabilities responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/capabilities response fields
Field	Type	Required
`approvals`	boolean	yes
`environment`	string (live, test)	yes
`formats`	array of string	yes
`limits`	object	yes
`max_pages`	integer	yes
`max_upload_bytes`	integer	yes
`numbers`	boolean	yes
`price_version`	string	yes
`provider`	string	yes
`rates`	object	yes
`receive`	boolean	yes
`routes`	array of string	yes
`scopes`	array of string	yes
`send`	boolean	yes

Example

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

GET `/v1/service-status`

Customer-safe availability

Responses

GET /v1/service-status responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/service-status response fields
Field	Type	Required
`database`	boolean	yes
`environment`	string (live, test)	yes
`provider`	string	yes
`status`	string (ok, degraded)	yes
`status_page`	string or null	no
`version`	string	yes
`worker_beat_age_s`	integer or null	no

Example

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

extractions

GET /v1/classifications Classifications, newest first
POST /v1/classifications Classify a received fax or a document into one of your document types, or abstain
GET /v1/classifications/{classification_id} One classification
GET /v1/document-summaries Summaries, newest first
POST /v1/document-summaries Summarise a received fax or a document; every sentence cites its pages
GET /v1/document-summaries/{summary_id} One summary
GET /v1/extraction-schemas Your extraction schemas
POST /v1/extraction-schemas Save a versioned extraction schema (the same name again is the next version)
GET /v1/extraction-schemas/{schema_id} One schema version
GET /v1/extractions Extractions, newest first
POST /v1/extractions Read a received fax or a document: OCR per page, then fields against a schema
GET /v1/extractions/{extraction_id} One extraction with its corrections
POST /v1/extractions/{extraction_id}/corrections Record a reviewer's correction of one field (stored beside the extraction, never merged)

GET `/v1/classifications`

Classifications, newest first

Parameters

GET /v1/classifications parameters
Name	In	Type	Required	Notes
`inbox_item_id`	query	string or null	no
`document_id`	query	string or null	no
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/classifications responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/classifications response fields
Field	Type	Required	Description
`items`	array of object Extraction	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/classifications`

Classify a received fax or a document into one of your document types, or abstain

Request body application/json, required

POST /v1/classifications request body
Field	Type	Required	Description
`abstain_below`	number	no
`document_id`	string or null	no
`document_types`	array of string	yes
`inbox_item_id`	string or null	no
`max_pages`	integer or null	no
`strict`	boolean	no	Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning.
`strong_model_if_below`	number	no

Responses

POST /v1/classifications responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/classifications response fields
Field	Type	Required	Description
`completed_at`	string or null	yes
`confidence`	number or null	yes
`corrections`	array of object or null	no
`created_at`	string	yes
`created_by`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes	The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so.
`environment`	string (live, test)	yes
`error_code`	string or null	yes
`id`	string	yes
`inbox_item_id`	string or null	yes
`kind`	string (extract, classify, summarize)	yes
`models`	object	yes
`options`	object	yes
`output`	object or null	yes
`pages`	array of object ExtractionPage	yes
`pages_escalated`	integer	yes
`pages_processed`	integer	yes
`pages_requested`	integer	yes
`price_micro`	integer	yes
`provider_cost_micro`	integer	yes
`schema`	object or null	no
`schema_id`	string or null	yes
`started_at`	string or null	yes
`status`	string (pending, queued, running, completed, failed)	yes

Example

curl https://api.faxforagents.com/v1/classifications \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/classifications/{classification_id}`

One classification

Parameters

GET /v1/classifications/{classification_id} parameters
Name	In	Type	Required	Notes
`classification_id`	path	string	yes

Responses

GET /v1/classifications/{classification_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/classifications/{classification_id} response fields
Field	Type	Required	Description
`completed_at`	string or null	yes
`confidence`	number or null	yes
`corrections`	array of object or null	no
`created_at`	string	yes
`created_by`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes	The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so.
`environment`	string (live, test)	yes
`error_code`	string or null	yes
`id`	string	yes
`inbox_item_id`	string or null	yes
`kind`	string (extract, classify, summarize)	yes
`models`	object	yes
`options`	object	yes
`output`	object or null	yes
`pages`	array of object ExtractionPage	yes
`pages_escalated`	integer	yes
`pages_processed`	integer	yes
`pages_requested`	integer	yes
`price_micro`	integer	yes
`provider_cost_micro`	integer	yes
`schema`	object or null	no
`schema_id`	string or null	yes
`started_at`	string or null	yes
`status`	string (pending, queued, running, completed, failed)	yes

Example

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

GET `/v1/document-summaries`

Summaries, newest first

Parameters

GET /v1/document-summaries parameters
Name	In	Type	Required	Notes
`inbox_item_id`	query	string or null	no
`document_id`	query	string or null	no
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/document-summaries responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/document-summaries response fields
Field	Type	Required	Description
`items`	array of object Extraction	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/document-summaries`

Summarise a received fax or a document; every sentence cites its pages

Request body application/json, required

POST /v1/document-summaries request body
Field	Type	Required	Description
`document_id`	string or null	no
`inbox_item_id`	string or null	no
`max_pages`	integer or null	no
`strict`	boolean	no	Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning.
`strong_model_if_below`	number	no

Responses

POST /v1/document-summaries responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/document-summaries response fields
Field	Type	Required	Description
`completed_at`	string or null	yes
`confidence`	number or null	yes
`corrections`	array of object or null	no
`created_at`	string	yes
`created_by`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes	The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so.
`environment`	string (live, test)	yes
`error_code`	string or null	yes
`id`	string	yes
`inbox_item_id`	string or null	yes
`kind`	string (extract, classify, summarize)	yes
`models`	object	yes
`options`	object	yes
`output`	object or null	yes
`pages`	array of object ExtractionPage	yes
`pages_escalated`	integer	yes
`pages_processed`	integer	yes
`pages_requested`	integer	yes
`price_micro`	integer	yes
`provider_cost_micro`	integer	yes
`schema`	object or null	no
`schema_id`	string or null	yes
`started_at`	string or null	yes
`status`	string (pending, queued, running, completed, failed)	yes

Example

curl https://api.faxforagents.com/v1/document-summaries \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/document-summaries/{summary_id}`

One summary

Parameters

GET /v1/document-summaries/{summary_id} parameters
Name	In	Type	Required	Notes
`summary_id`	path	string	yes

Responses

GET /v1/document-summaries/{summary_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/document-summaries/{summary_id} response fields
Field	Type	Required	Description
`completed_at`	string or null	yes
`confidence`	number or null	yes
`corrections`	array of object or null	no
`created_at`	string	yes
`created_by`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes	The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so.
`environment`	string (live, test)	yes
`error_code`	string or null	yes
`id`	string	yes
`inbox_item_id`	string or null	yes
`kind`	string (extract, classify, summarize)	yes
`models`	object	yes
`options`	object	yes
`output`	object or null	yes
`pages`	array of object ExtractionPage	yes
`pages_escalated`	integer	yes
`pages_processed`	integer	yes
`pages_requested`	integer	yes
`price_micro`	integer	yes
`provider_cost_micro`	integer	yes
`schema`	object or null	no
`schema_id`	string or null	yes
`started_at`	string or null	yes
`status`	string (pending, queued, running, completed, failed)	yes

Example

curl https://api.faxforagents.com/v1/document-summaries/SUMMARY_ID \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/extraction-schemas`

Your extraction schemas

Responses

GET /v1/extraction-schemas responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/extraction-schemas response fields
Field	Type	Required	Description
`items`	array of object ExtractionSchema	yes

Example

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

POST `/v1/extraction-schemas`

Save a versioned extraction schema (the same name again is the next version)

Request body application/json, required

POST /v1/extraction-schemas request body
Field	Type	Required
`description`	string or null	no
`name`	string	yes
`schema`	object	yes

Responses

POST /v1/extraction-schemas responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/extraction-schemas response fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`description`	string or null	yes
`id`	string	yes
`name`	string	yes
`schema`	object	yes
`status`	string	yes
`version`	integer	yes

Example

curl https://api.faxforagents.com/v1/extraction-schemas \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/extraction-schemas/{schema_id}`

One schema version

Parameters

GET /v1/extraction-schemas/{schema_id} parameters
Name	In	Type	Required	Notes
`schema_id`	path	string	yes

Responses

GET /v1/extraction-schemas/{schema_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/extraction-schemas/{schema_id} response fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`description`	string or null	yes
`id`	string	yes
`name`	string	yes
`schema`	object	yes
`status`	string	yes
`version`	integer	yes

Example

curl https://api.faxforagents.com/v1/extraction-schemas/SCHEMA_ID \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/extractions`

Extractions, newest first

Parameters

GET /v1/extractions parameters
Name	In	Type	Required	Notes
`inbox_item_id`	query	string or null	no
`document_id`	query	string or null	no
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/extractions responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/extractions response fields
Field	Type	Required	Description
`items`	array of object Extraction	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/extractions`

Read a received fax or a document: OCR per page, then fields against a schema

Request body application/json, required

POST /v1/extractions request body
Field	Type	Required	Description
`document_id`	string or null	no
`inbox_item_id`	string or null	no
`max_pages`	integer or null	no
`schema`	object or null	no	A JSON Schema object of string, number, boolean or date fields with descriptions.
`schema_id`	string or null	no
`strict`	boolean	no	Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning.
`strong_model_if_below`	number	no

Responses

POST /v1/extractions responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/extractions response fields
Field	Type	Required	Description
`completed_at`	string or null	yes
`confidence`	number or null	yes
`corrections`	array of object or null	no
`created_at`	string	yes
`created_by`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes	The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so.
`environment`	string (live, test)	yes
`error_code`	string or null	yes
`id`	string	yes
`inbox_item_id`	string or null	yes
`kind`	string (extract, classify, summarize)	yes
`models`	object	yes
`options`	object	yes
`output`	object or null	yes
`pages`	array of object ExtractionPage	yes
`pages_escalated`	integer	yes
`pages_processed`	integer	yes
`pages_requested`	integer	yes
`price_micro`	integer	yes
`provider_cost_micro`	integer	yes
`schema`	object or null	no
`schema_id`	string or null	yes
`started_at`	string or null	yes
`status`	string (pending, queued, running, completed, failed)	yes

Example

curl https://api.faxforagents.com/v1/extractions \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/extractions/{extraction_id}`

One extraction with its corrections

Parameters

GET /v1/extractions/{extraction_id} parameters
Name	In	Type	Required	Notes
`extraction_id`	path	string	yes

Responses

GET /v1/extractions/{extraction_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/extractions/{extraction_id} response fields
Field	Type	Required	Description
`completed_at`	string or null	yes
`confidence`	number or null	yes
`corrections`	array of object or null	no
`created_at`	string	yes
`created_by`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes	The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so.
`environment`	string (live, test)	yes
`error_code`	string or null	yes
`id`	string	yes
`inbox_item_id`	string or null	yes
`kind`	string (extract, classify, summarize)	yes
`models`	object	yes
`options`	object	yes
`output`	object or null	yes
`pages`	array of object ExtractionPage	yes
`pages_escalated`	integer	yes
`pages_processed`	integer	yes
`pages_requested`	integer	yes
`price_micro`	integer	yes
`provider_cost_micro`	integer	yes
`schema`	object or null	no
`schema_id`	string or null	yes
`started_at`	string or null	yes
`status`	string (pending, queued, running, completed, failed)	yes

Example

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

POST `/v1/extractions/{extraction_id}/corrections`

Record a reviewer's correction of one field (stored beside the extraction, never merged)

Parameters

POST /v1/extractions/{extraction_id}/corrections parameters
Name	In	Type	Required	Notes
`extraction_id`	path	string	yes

Request body application/json, required

POST /v1/extractions/{extraction_id}/corrections request body
Field	Type	Required
`field`	string or null	no
`note`	string or null	no
`value`	any	no

Responses

POST /v1/extractions/{extraction_id}/corrections responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/extractions/{extraction_id}/corrections response fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`extraction_id`	string	yes
`field`	string	yes
`id`	string	yes
`note`	string or null	yes
`value`	any	yes

Example

curl https://api.faxforagents.com/v1/extractions/EXTRACTION_ID/corrections \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

numbers

GET /v1/coverage Where we send and where we host numbers
GET /v1/number-inventory Fax-capable numbers for sale
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 and inbound route 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)

GET `/v1/coverage`

Where we send and where we host numbers

Responses

GET /v1/coverage responses
Status	Meaning
`200`	Successful Response

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

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
`422`	Validation Error

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_..."

POST `/v1/number-orders`

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

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
`422`	Validation Error

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_..."

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

Read a number order

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
`422`	Validation Error

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

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
`422`	Validation Error

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

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
`422`	Validation Error

Response fields

GET /v1/numbers/{number_id} response fields
Field	Type	Required
`activated_at`	string or null	yes
`country`	string	yes
`created_at`	string	yes
`currency`	string	yes
`e164`	string	yes
`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 and inbound route of a number

Parameters

PATCH /v1/numbers/{number_id} parameters
Name	In	Type	Required	Notes
`number_id`	path	string	yes

Request body application/json, required

PATCH /v1/numbers/{number_id} request body
Field	Type	Required
`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
`422`	Validation Error

Response fields

PATCH /v1/numbers/{number_id} response fields
Field	Type	Required
`activated_at`	string or null	yes
`country`	string	yes
`created_at`	string	yes
`currency`	string	yes
`e164`	string	yes
`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_..."

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

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

Parameters

POST /v1/numbers/{number_id}/release-requests parameters
Name	In	Type	Required	Notes
`number_id`	path	string	yes

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
`422`	Validation Error

Response fields

POST /v1/numbers/{number_id}/release-requests response fields
Field	Type	Required
`activated_at`	string or null	yes
`country`	string	yes
`created_at`	string	yes
`currency`	string	yes
`e164`	string	yes
`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_..."

GET `/v1/port-orders`

Port orders and port-out requests

Responses

GET /v1/port-orders responses
Status	Meaning
`200`	Successful Response

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)

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
`422`	Validation Error

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_..."

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

One port order

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
`422`	Validation Error

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

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
`422`	Validation Error

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_..."

POST `/v1/portability-checks`

Can these numbers port in

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
`422`	Validation Error

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_..."

POST `/v1/sender-verifications`

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

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
`422`	Validation Error

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_..."

documents

GET /v1/documents List documents, newest first
POST /v1/documents Create an immutable document from an upload or from text
DELETE /v1/documents/{document_id} Delete a document (its bytes and previews)
GET /v1/documents/{document_id} Read a document's hash, pages and validation state
GET /v1/documents/{document_id}/content The PDF bytes behind a signed URL (no API key)
GET /v1/documents/{document_id}/download A short-lived signed download URL
GET /v1/documents/{document_id}/pages Rendered pages with signed preview URLs
GET /v1/documents/{document_id}/pages/{page_number}/content A page PNG behind a signed URL (no API key)
GET /v1/documents/{document_id}/validation Validation warnings
POST /v1/uploads Create a bounded upload session
DELETE /v1/uploads/{upload_id} Cancel an incomplete upload
POST /v1/uploads/{upload_id}/complete Finalize an upload (size and hash checked)
PUT /v1/uploads/{upload_id}/content Send the bytes to a signed upload URL (no API key)

GET `/v1/documents`

List documents, newest first

Parameters

GET /v1/documents parameters
Name	In	Type	Required	Notes
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/documents responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/documents response fields
Field	Type	Required	Description
`items`	array of object Document	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/documents`

Create an immutable document from an upload or from text

Request body application/json, required

POST /v1/documents request body
Field	Type	Required	Description
`filename`	string or null	no
`html`	string or null	no	HTML rendered to PDF by a headless browser with scripts off and no network: inline CSS and data: images print, external resources are counted as blocked. US letter unless @page says otherwise. At most 2 MiB.
`markdown`	string or null	no	Markdown (headings, lists, emphasis, code) rendered to PDF.
`text`	string or null	no	Plain text rendered to a letter PDF.
`upload_id`	string or null	no

Responses

POST /v1/documents responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/documents response fields
Field	Type	Required
`content_type`	string	yes
`created_at`	string	yes
`deleted_at`	string or null	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`filename`	string	yes
`id`	string	yes
`page_count`	integer	yes
`render_reason`	string or null	yes
`render_status`	string	yes
`sha256`	string	yes
`size_bytes`	integer	yes
`source`	string	yes
`status`	string	yes
`upload_id`	string or null	yes
`validation`	object	yes

Example

curl https://api.faxforagents.com/v1/documents \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/documents/{document_id}`

Delete a document (its bytes and previews)

Parameters

DELETE /v1/documents/{document_id} parameters
Name	In	Type	Required	Notes
`document_id`	path	string	yes

Responses

DELETE /v1/documents/{document_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

DELETE /v1/documents/{document_id} response fields
Field	Type	Required	Description
`deleted`	boolean	no
`id`	string	yes

Example

curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/documents/{document_id}`

Read a document's hash, pages and validation state

Parameters

GET /v1/documents/{document_id} parameters
Name	In	Type	Required	Notes
`document_id`	path	string	yes

Responses

GET /v1/documents/{document_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/documents/{document_id} response fields
Field	Type	Required
`content_type`	string	yes
`created_at`	string	yes
`deleted_at`	string or null	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`filename`	string	yes
`id`	string	yes
`page_count`	integer	yes
`render_reason`	string or null	yes
`render_status`	string	yes
`sha256`	string	yes
`size_bytes`	integer	yes
`source`	string	yes
`status`	string	yes
`upload_id`	string or null	yes
`validation`	object	yes

Example

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

GET `/v1/documents/{document_id}/content`

The PDF bytes behind a signed URL (no API key)

Parameters

GET /v1/documents/{document_id}/content parameters
Name	In	Type	Required
`document_id`	path	string	yes
`exp`	query	string or null	no
`sig`	query	string or null	no

Responses

GET /v1/documents/{document_id}/content responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/content \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/documents/{document_id}/download`

A short-lived signed download URL

Parameters

GET /v1/documents/{document_id}/download parameters
Name	In	Type	Required	Notes
`document_id`	path	string	yes

Responses

GET /v1/documents/{document_id}/download responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/documents/{document_id}/download response fields
Field	Type	Required
`content_type`	string	yes
`expires_at`	string	yes
`url`	string	yes

Example

curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/download \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/documents/{document_id}/pages`

Rendered pages with signed preview URLs

Parameters

GET /v1/documents/{document_id}/pages parameters
Name	In	Type	Required	Notes
`document_id`	path	string	yes

Responses

GET /v1/documents/{document_id}/pages responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/documents/{document_id}/pages response fields
Field	Type	Required
`document_id`	string	yes
`items`	array of object PagePreview	yes
`page_count`	integer	yes
`render_reason`	string or null	yes
`render_status`	string	yes

Example

curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/pages \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/documents/{document_id}/pages/{page_number}/content`

A page PNG behind a signed URL (no API key)

Parameters

GET /v1/documents/{document_id}/pages/{page_number}/content parameters
Name	In	Type	Required
`document_id`	path	string	yes
`page_number`	path	integer	yes
`exp`	query	string or null	no
`sig`	query	string or null	no

Responses

GET /v1/documents/{document_id}/pages/{page_number}/content responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/pages/PAGE_NUMBER/content \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/documents/{document_id}/validation`

Validation warnings

Parameters

GET /v1/documents/{document_id}/validation parameters
Name	In	Type	Required	Notes
`document_id`	path	string	yes

Responses

GET /v1/documents/{document_id}/validation responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/documents/{document_id}/validation response fields
Field	Type	Required
`id`	string	yes
`page_count`	integer	yes
`render_reason`	string or null	yes
`render_status`	string	yes
`status`	string	yes
`warnings`	array of object	yes

Example

curl https://api.faxforagents.com/v1/documents/DOCUMENT_ID/validation \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/uploads`

Create a bounded upload session

Request body application/json, required

POST /v1/uploads request body
Field	Type	Required	Description
`content_type`	string	no	application/pdf, image/png, image/jpeg or image/tiff. An image becomes 8-bit gray letter pages, since fax is monochrome. A frame wider than it is tall is rotated. A frame above 300 dpi letter is downsampled. Every TIFF frame is a page. PNG and JPEG take the first frame. The bytes must be the declared type.
`filename`	string	yes
`size_bytes`	integer	yes

Responses

POST /v1/uploads responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/uploads response fields
Field	Type	Required
`completed_at`	string or null	yes
`content_type`	string	yes
`created_at`	string	yes
`declared_size`	integer	yes
`expires_at`	string	yes
`filename`	string	yes
`id`	string	yes
`received_size`	integer	yes
`sha256`	string or null	yes
`status`	string	yes
`upload_method`	string or null	no
`upload_url`	string or null	no
`upload_url_expires_at`	string or null	no

Example

curl https://api.faxforagents.com/v1/uploads \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/uploads/{upload_id}`

Cancel an incomplete upload

Parameters

DELETE /v1/uploads/{upload_id} parameters
Name	In	Type	Required	Notes
`upload_id`	path	string	yes

Responses

DELETE /v1/uploads/{upload_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

DELETE /v1/uploads/{upload_id} response fields
Field	Type	Required	Description
`deleted`	boolean	no
`id`	string	yes

Example

curl https://api.faxforagents.com/v1/uploads/UPLOAD_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/uploads/{upload_id}/complete`

Finalize an upload (size and hash checked)

Parameters

POST /v1/uploads/{upload_id}/complete parameters
Name	In	Type	Required	Notes
`upload_id`	path	string	yes

Request body application/json, required

POST /v1/uploads/{upload_id}/complete request body
Field	Type	Required	Description
`sha256`	string or null	no	Optional: fail if the bytes differ.

Responses

POST /v1/uploads/{upload_id}/complete responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/uploads/{upload_id}/complete response fields
Field	Type	Required
`completed_at`	string or null	yes
`content_type`	string	yes
`created_at`	string	yes
`declared_size`	integer	yes
`expires_at`	string	yes
`filename`	string	yes
`id`	string	yes
`received_size`	integer	yes
`sha256`	string or null	yes
`status`	string	yes
`upload_method`	string or null	no
`upload_url`	string or null	no
`upload_url_expires_at`	string or null	no

Example

curl https://api.faxforagents.com/v1/uploads/UPLOAD_ID/complete \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

PUT `/v1/uploads/{upload_id}/content`

Send the bytes to a signed upload URL (no API key)

Parameters

PUT /v1/uploads/{upload_id}/content parameters
Name	In	Type	Required
`upload_id`	path	string	yes
`exp`	query	string or null	no
`sig`	query	string or null	no

Responses

PUT /v1/uploads/{upload_id}/content responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PUT /v1/uploads/{upload_id}/content response fields
Field	Type	Required
`completed_at`	string or null	yes
`content_type`	string	yes
`created_at`	string	yes
`declared_size`	integer	yes
`expires_at`	string	yes
`filename`	string	yes
`id`	string	yes
`received_size`	integer	yes
`sha256`	string or null	yes
`status`	string	yes
`upload_method`	string or null	no
`upload_url`	string or null	no
`upload_url_expires_at`	string or null	no

Example

curl https://api.faxforagents.com/v1/uploads/UPLOAD_ID/content \
  -X PUT \
  -H "Authorization: Bearer ffa_test_..."

events

GET /v1/events Events for reconciliation, oldest first from the cursor

GET `/v1/events`

Events for reconciliation, oldest first from the cursor

Parameters

GET /v1/events parameters
Name	In	Type	Required	Notes
`type`	query	string or null	no
`cursor`	query	string or null	no	The cursor from the previous page (opaque).
`limit`	query	integer	no	Default `100`.

Responses

GET /v1/events responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/events response fields
Field	Type	Required	Description
`items`	array of object Event	yes
`next_cursor`	string or null	no

Example

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

quotes

POST /v1/fax-quotes Price an exact document to one destination
GET /v1/fax-quotes/{quote_id} Read a quote

POST `/v1/fax-quotes`

Price an exact document to one destination

Request body application/json, required

POST /v1/fax-quotes request body
Field	Type	Required	Description
`cover`	object or null	no	Cover sheet fields: to_name, from_name, subject, message. Counts as a page.
`document_id`	string	yes
`from`	string or null	no	A number you own; omit for the shared pool.
`to`	string	yes	Destination in E.164, for example +12025550123.

Responses

POST /v1/fax-quotes responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/fax-quotes response fields
Field	Type	Required
`amount_micro`	integer	yes
`authorization_required`	boolean	yes
`billable_pages`	integer	yes
`consumed_by_job_id`	string or null	yes
`cover`	object or null	yes
`cover_pages`	integer	yes
`created_at`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes
`document_sha256`	string	yes
`environment`	string (live, test)	yes
`expired`	boolean	yes
`expires_at`	string	yes
`from`	string or null	no
`id`	string	yes
`per_page_micro`	integer	no
`price_version`	string	yes
`route`	string	yes
`route_label`	string	no
`to`	string	yes
`warnings`	array of object	yes

Example

curl https://api.faxforagents.com/v1/fax-quotes \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/fax-quotes/{quote_id}`

Read a quote

Parameters

GET /v1/fax-quotes/{quote_id} parameters
Name	In	Type	Required	Notes
`quote_id`	path	string	yes

Responses

GET /v1/fax-quotes/{quote_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/fax-quotes/{quote_id} response fields
Field	Type	Required
`amount_micro`	integer	yes
`authorization_required`	boolean	yes
`billable_pages`	integer	yes
`consumed_by_job_id`	string or null	yes
`cover`	object or null	yes
`cover_pages`	integer	yes
`created_at`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes
`document_sha256`	string	yes
`environment`	string (live, test)	yes
`expired`	boolean	yes
`expires_at`	string	yes
`from`	string or null	no
`id`	string	yes
`per_page_micro`	integer	no
`price_version`	string	yes
`route`	string	yes
`route_label`	string	no
`to`	string	yes
`warnings`	array of object	yes

Example

curl https://api.faxforagents.com/v1/fax-quotes/QUOTE_ID \
  -H "Authorization: Bearer ffa_test_..."

faxes

GET /v1/faxes List fax jobs, newest first
POST /v1/faxes Send a quoted fax (Idempotency-Key recommended)
GET /v1/faxes/{fax_id} Read a fax job (with evidence once delivered)
GET /v1/faxes/{fax_id}/attempts Attempt history
POST /v1/faxes/{fax_id}/cancel Cancel if still possible (best effort once sending)
GET /v1/faxes/{fax_id}/events Ordered events of one fax
GET /v1/faxes/{fax_id}/receipt Delivery evidence as a receipt (JSON)

GET `/v1/faxes`

List fax jobs, newest first

Parameters

GET /v1/faxes parameters
Name	In	Type	Required	Notes
`state`	query	string or null	no
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/faxes responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/faxes response fields
Field	Type	Required	Description
`items`	array of object FaxJob	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/faxes`

Send a quoted fax (Idempotency-Key recommended)

Request body application/json, required

M9: an approved request authorizes the send; without one a quote that needs authorization is evaluated against the caller's delegated policies.

POST /v1/faxes request body
Field	Type	Required	Description
`approval_id`	string or null	no	An approved approval request bound to this quote. Consumed by this one send.
`client_reference`	string or null	no
`quote_id`	string	yes

Responses

POST /v1/faxes responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/faxes response fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`attempt_count`	integer	yes
`billable_pages`	integer	yes
`cancel_requested_at`	string or null	yes
`captured_micro`	integer	yes
`client_reference`	string or null	yes
`completed_at`	string or null	yes
`cover_pages`	integer	yes
`created_at`	string	yes
`currency`	string	yes
`direction`	string	yes
`document_id`	string	yes
`document_sha256`	string	yes
`environment`	string (live, test)	yes
`evidence`	object or null	no	The carrier's evidence once delivered or partial; null before.
`failure_code`	string or null	yes
`from`	string or null	no
`id`	string	yes
`pages_sent`	integer	yes
`provider`	string	yes
`provider_ref`	string or null	yes
`quote_id`	string or null	yes
`route`	string	yes
`state`	string (queued, active, partial, failed, unknown, delivered)	yes
`to`	string	yes
`transmitted_sha256`	string or null	yes
`updated_at`	string	yes

Example

curl https://api.faxforagents.com/v1/faxes \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/faxes/{fax_id}`

Read a fax job (with evidence once delivered)

Parameters

GET /v1/faxes/{fax_id} parameters
Name	In	Type	Required	Notes
`fax_id`	path	string	yes

Responses

GET /v1/faxes/{fax_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/faxes/{fax_id} response fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`attempt_count`	integer	yes
`billable_pages`	integer	yes
`cancel_requested_at`	string or null	yes
`captured_micro`	integer	yes
`client_reference`	string or null	yes
`completed_at`	string or null	yes
`cover_pages`	integer	yes
`created_at`	string	yes
`currency`	string	yes
`direction`	string	yes
`document_id`	string	yes
`document_sha256`	string	yes
`environment`	string (live, test)	yes
`evidence`	object or null	no	The carrier's evidence once delivered or partial; null before.
`failure_code`	string or null	yes
`from`	string or null	no
`id`	string	yes
`pages_sent`	integer	yes
`provider`	string	yes
`provider_ref`	string or null	yes
`quote_id`	string or null	yes
`route`	string	yes
`state`	string (queued, active, partial, failed, unknown, delivered)	yes
`to`	string	yes
`transmitted_sha256`	string or null	yes
`updated_at`	string	yes

Example

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

GET `/v1/faxes/{fax_id}/attempts`

Attempt history

Parameters

GET /v1/faxes/{fax_id}/attempts parameters
Name	In	Type	Required	Notes
`fax_id`	path	string	yes

Responses

GET /v1/faxes/{fax_id}/attempts responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/faxes/{fax_id}/attempts response fields
Field	Type	Required	Description
`items`	array of object Attempt	yes

Example

curl https://api.faxforagents.com/v1/faxes/FAX_ID/attempts \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/faxes/{fax_id}/cancel`

Cancel if still possible (best effort once sending)

Parameters

POST /v1/faxes/{fax_id}/cancel parameters
Name	In	Type	Required	Notes
`fax_id`	path	string	yes

Responses

POST /v1/faxes/{fax_id}/cancel responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/faxes/{fax_id}/cancel response fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`attempt_count`	integer	yes
`billable_pages`	integer	yes
`cancel_requested_at`	string or null	yes
`captured_micro`	integer	yes
`client_reference`	string or null	yes
`completed_at`	string or null	yes
`cover_pages`	integer	yes
`created_at`	string	yes
`currency`	string	yes
`direction`	string	yes
`document_id`	string	yes
`document_sha256`	string	yes
`environment`	string (live, test)	yes
`evidence`	object or null	no	The carrier's evidence once delivered or partial; null before.
`failure_code`	string or null	yes
`from`	string or null	no
`id`	string	yes
`pages_sent`	integer	yes
`provider`	string	yes
`provider_ref`	string or null	yes
`quote_id`	string or null	yes
`route`	string	yes
`state`	string (queued, active, partial, failed, unknown, delivered)	yes
`to`	string	yes
`transmitted_sha256`	string or null	yes
`updated_at`	string	yes

Example

curl https://api.faxforagents.com/v1/faxes/FAX_ID/cancel \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/faxes/{fax_id}/events`

Ordered events of one fax

Parameters

GET /v1/faxes/{fax_id}/events parameters
Name	In	Type	Required	Notes
`fax_id`	path	string	yes

Responses

GET /v1/faxes/{fax_id}/events responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/faxes/{fax_id}/events response fields
Field	Type	Required	Description
`items`	array of object Event	yes
`next_cursor`	string or null	no

Example

curl https://api.faxforagents.com/v1/faxes/FAX_ID/events \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/faxes/{fax_id}/receipt`

Delivery evidence as a receipt (JSON)

Parameters

GET /v1/faxes/{fax_id}/receipt parameters
Name	In	Type	Required	Notes
`fax_id`	path	string	yes

Responses

GET /v1/faxes/{fax_id}/receipt responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/faxes/{fax_id}/receipt response fields
Field	Type	Required
`amount_micro`	integer	yes
`attempts`	array of object Attempt	yes
`billable_pages`	integer	yes
`captured_micro`	integer	yes
`completed_at`	string or null	yes
`created_at`	string	yes
`currency`	string	yes
`document_sha256`	string	yes
`evidence`	object or null	yes
`failure_code`	string or null	yes
`fax_job_id`	string	yes
`from`	string or null	no
`generated_at`	string	yes
`note`	string	yes
`pages_sent`	integer	yes
`provider`	string	yes
`state`	string	yes
`to`	string	yes
`transmitted_sha256`	string or null	yes

Example

curl https://api.faxforagents.com/v1/faxes/FAX_ID/receipt \
  -H "Authorization: Bearer ffa_test_..."

inbox

GET /v1/inbox Received faxes, newest first (metadata only)
DELETE /v1/inbox/{inbox_id} Delete a received fax
GET /v1/inbox/{inbox_id} One received fax with its text as data
PATCH /v1/inbox/{inbox_id} Mark a received fax read or archived
GET /v1/inbox/{inbox_id}/content The received PDF behind a signed URL (no API key)
GET /v1/inbox/{inbox_id}/download A short-lived signed link to the received PDF

GET `/v1/inbox`

Received faxes, newest first (metadata only)

Parameters

GET /v1/inbox parameters
Name	In	Type	Required	Notes
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.
`status`	query	string (received, read, archived) or null	no

Responses

GET /v1/inbox responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/inbox response fields
Field	Type	Required	Description
`items`	array of object faxforagents__api__routes__inbox__InboxItem	yes
`next_cursor`	string or null	no

Example

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

DELETE `/v1/inbox/{inbox_id}`

Delete a received fax

Parameters

DELETE /v1/inbox/{inbox_id} parameters
Name	In	Type	Required	Notes
`inbox_id`	path	string	yes

Responses

DELETE /v1/inbox/{inbox_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

DELETE /v1/inbox/{inbox_id} response fields
Field	Type	Required	Description
`deleted`	boolean	no
`id`	string	yes

Example

curl https://api.faxforagents.com/v1/inbox/INBOX_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/inbox/{inbox_id}`

One received fax with its text as data

Parameters

GET /v1/inbox/{inbox_id} parameters
Name	In	Type	Required	Notes
`inbox_id`	path	string	yes

Responses

GET /v1/inbox/{inbox_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/inbox/{inbox_id} response fields
Field	Type	Required
`amount_micro`	integer	no
`document`	object or null	no
`document_id`	string or null	yes
`duration_secs`	integer or null	no
`environment`	string (live, test)	no
`expires_at`	string or null	no
`extraction_id`	string or null	no
`from`	string or null	no
`id`	string	yes
`media_status`	string	no
`note`	string or null	no
`number_id`	string or null	no
`pages`	integer	yes
`partial_content`	boolean	no
`project_id`	string or null	no
`provider`	string	no
`read_at`	string or null	no
`received_at`	string	yes
`status`	string	yes
`text`	string or null	no
`to`	string	yes

Example

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

PATCH `/v1/inbox/{inbox_id}`

Mark a received fax read or archived

Parameters

PATCH /v1/inbox/{inbox_id} parameters
Name	In	Type	Required	Notes
`inbox_id`	path	string	yes

Request body application/json, required

PATCH /v1/inbox/{inbox_id} request body
Field	Type	Required	Description
`status`	string (received, read, archived) or null	no

Responses

PATCH /v1/inbox/{inbox_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/inbox/{inbox_id} response fields
Field	Type	Required
`amount_micro`	integer	no
`document_id`	string or null	yes
`duration_secs`	integer or null	no
`environment`	string (live, test)	no
`expires_at`	string or null	no
`from`	string or null	no
`id`	string	yes
`media_status`	string	no
`note`	string or null	no
`number_id`	string or null	no
`pages`	integer	yes
`partial_content`	boolean	no
`project_id`	string or null	no
`provider`	string	no
`read_at`	string or null	no
`received_at`	string	yes
`status`	string	yes
`to`	string	yes

Example

curl https://api.faxforagents.com/v1/inbox/INBOX_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/inbox/{inbox_id}/content`

The received PDF behind a signed URL (no API key)

Parameters

GET /v1/inbox/{inbox_id}/content parameters
Name	In	Type	Required
`inbox_id`	path	string	yes
`exp`	query	string or null	no
`sig`	query	string or null	no

Responses

GET /v1/inbox/{inbox_id}/content responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/inbox/INBOX_ID/content \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/inbox/{inbox_id}/download`

A short-lived signed link to the received PDF

Parameters

GET /v1/inbox/{inbox_id}/download parameters
Name	In	Type	Required	Notes
`inbox_id`	path	string	yes

Responses

GET /v1/inbox/{inbox_id}/download responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/inbox/{inbox_id}/download response fields
Field	Type	Required
`content_type`	string	yes
`expires_at`	string	yes
`url`	string	yes

Example

curl https://api.faxforagents.com/v1/inbox/INBOX_ID/download \
  -H "Authorization: Bearer ffa_test_..."

members

GET /v1/invitations Open invitations
POST /v1/invitations Invite someone by email (a link that works for 7 days)
DELETE /v1/invitations/{invitation_id} Withdraw an invitation
GET /v1/members The organization's members
DELETE /v1/members/{member_id} Remove a member (owner)
PATCH /v1/members/{member_id} Change a member's role

GET `/v1/invitations`

Open invitations

Responses

GET /v1/invitations responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/invitations response fields
Field	Type	Required	Description
`items`	array of object Invitation	yes

Example

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

POST `/v1/invitations`

Invite someone by email (a link that works for 7 days)

Request body application/json, required

POST /v1/invitations request body
Field	Type	Required	Description
`email`	string (email)	yes
`role`	string (owner, admin, member, viewer)	no

Responses

POST /v1/invitations responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/invitations response fields
Field	Type	Required
`accepted_at`	string or null	yes
`created_at`	string	yes
`email`	string	yes
`expires_at`	string	yes
`id`	string	yes
`invited_by`	string	yes
`role`	string (owner, admin, member, viewer)	yes

Example

curl https://api.faxforagents.com/v1/invitations \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/invitations/{invitation_id}`

Withdraw an invitation

Parameters

DELETE /v1/invitations/{invitation_id} parameters
Name	In	Type	Required	Notes
`invitation_id`	path	string	yes

Responses

DELETE /v1/invitations/{invitation_id} responses
Status	Meaning
`204`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/invitations/INVITATION_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/members`

The organization's members

Responses

GET /v1/members responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/members response fields
Field	Type	Required	Description
`items`	array of object Member	yes

Example

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

DELETE `/v1/members/{member_id}`

Remove a member (owner)

Parameters

DELETE /v1/members/{member_id} parameters
Name	In	Type	Required	Notes
`member_id`	path	string	yes

Responses

DELETE /v1/members/{member_id} responses
Status	Meaning
`204`	Successful Response
`422`	Validation Error

Example

curl https://api.faxforagents.com/v1/members/MEMBER_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

PATCH `/v1/members/{member_id}`

Change a member's role

Parameters

PATCH /v1/members/{member_id} parameters
Name	In	Type	Required	Notes
`member_id`	path	string	yes

Request body application/json, required

PATCH /v1/members/{member_id} request body
Field	Type	Required	Description
`role`	string (owner, admin, member, viewer) or null	no	Required. Optional in the schema so a foreign id is a 404 first.

Responses

PATCH /v1/members/{member_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/members/{member_id} response fields
Field	Type	Required
`created_at`	string	yes
`email`	string	yes
`id`	string	yes
`name`	string or null	yes
`role`	string (owner, admin, member, viewer)	yes
`user_id`	string or null	yes

Example

curl https://api.faxforagents.com/v1/members/MEMBER_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

organizations

GET /v1/organizations The organizations you belong to
GET /v1/organizations/current The organization you are looking at
PATCH /v1/organizations/current Rename the organization
POST /v1/organizations/current/deletion-requests Ask for the organization and its data to be deleted (owner)
POST /v1/organizations/current/export-requests Ask for an export of the organization's data (owner)

GET `/v1/organizations`

The organizations you belong to

Responses

GET /v1/organizations responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/organizations response fields
Field	Type	Required	Description
`items`	array of object OrganizationSummary	yes

Example

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

GET `/v1/organizations/current`

The organization you are looking at

Responses

GET /v1/organizations/current responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/organizations/current response fields
Field	Type	Required
`created_at`	string	yes
`id`	string	yes
`members`	integer	yes
`name`	string	yes
`role`	string (owner, admin, member, viewer) or null	yes

Example

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

PATCH `/v1/organizations/current`

Rename the organization

Request body application/json, required

PATCH /v1/organizations/current request body
Field	Type	Required	Description
`name`	string	yes

Responses

PATCH /v1/organizations/current responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/organizations/current response fields
Field	Type	Required
`created_at`	string	yes
`id`	string	yes
`members`	integer	yes
`name`	string	yes
`role`	string (owner, admin, member, viewer) or null	yes

Example

curl https://api.faxforagents.com/v1/organizations/current \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/organizations/current/deletion-requests`

Ask for the organization and its data to be deleted (owner)

Responses

POST /v1/organizations/current/deletion-requests responses
Status	Meaning
`202`	Successful Response

Response fields

POST /v1/organizations/current/deletion-requests response fields
Field	Type	Required
`kind`	string (export, deletion)	yes
`message`	string	yes
`requested`	boolean	yes

Example

curl https://api.faxforagents.com/v1/organizations/current/deletion-requests \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/organizations/current/export-requests`

Ask for an export of the organization's data (owner)

Responses

POST /v1/organizations/current/export-requests responses
Status	Meaning
`202`	Successful Response

Response fields

POST /v1/organizations/current/export-requests response fields
Field	Type	Required
`kind`	string (export, deletion)	yes
`message`	string	yes
`requested`	boolean	yes

Example

curl https://api.faxforagents.com/v1/organizations/current/export-requests \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

policies

GET /v1/policies List the organization's policies
POST /v1/policies Create a delegated policy (version 1)
GET /v1/policies/effective What the calling key may do on its own, and whether a human is needed otherwise
GET /v1/policies/{policy_id} Read a policy (its current version)
PATCH /v1/policies/{policy_id} Change a policy: a new immutable version
GET /v1/policies/{policy_id}/versions Every version, oldest first
POST /v1/policy-evaluations Dry run: would the calling key's policies allow this send? Never executes

GET `/v1/policies`

List the organization's policies

Responses

GET /v1/policies responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/policies response fields
Field	Type	Required	Description
`items`	array of object Policy	yes

Example

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

POST `/v1/policies`

Create a delegated policy (version 1)

Request body application/json, required

POST /v1/policies request body
Field	Type	Required	Description
`enabled`	boolean	no
`name`	string	yes
`purpose`	string or null	no	Why this policy exists. Shown, never evaluated.
`rules`	object	yes	See the PolicyRules schema in docs/APPROVALS.md.

Responses

POST /v1/policies responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/policies response fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`current_version_id`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`name`	string	yes
`purpose`	string or null	yes
`rules`	object	yes
`updated_at`	string	yes
`version`	integer	yes

Example

curl https://api.faxforagents.com/v1/policies \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/policies/effective`

What the calling key may do on its own, and whether a human is needed otherwise

Responses

GET /v1/policies/effective responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/policies/effective response fields
Field	Type	Required
`actor`	string	yes
`approval_required_without_policy`	boolean	yes
`environment`	string (live, test)	yes
`policies`	array of object Policy	yes
`rules_order`	array of string	yes
`under_policy`	boolean	yes

Example

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

GET `/v1/policies/{policy_id}`

Read a policy (its current version)

Parameters

GET /v1/policies/{policy_id} parameters
Name	In	Type	Required	Notes
`policy_id`	path	string	yes

Responses

GET /v1/policies/{policy_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/policies/{policy_id} response fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`current_version_id`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`name`	string	yes
`purpose`	string or null	yes
`rules`	object	yes
`updated_at`	string	yes
`version`	integer	yes

Example

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

PATCH `/v1/policies/{policy_id}`

Change a policy: a new immutable version

Parameters

PATCH /v1/policies/{policy_id} parameters
Name	In	Type	Required	Notes
`policy_id`	path	string	yes

Request body application/json, required

PATCH /v1/policies/{policy_id} request body
Field	Type	Required
`enabled`	boolean or null	no
`name`	string or null	no
`purpose`	string or null	no
`rules`	object or null	no

Responses

PATCH /v1/policies/{policy_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/policies/{policy_id} response fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`current_version_id`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`name`	string	yes
`purpose`	string or null	yes
`rules`	object	yes
`updated_at`	string	yes
`version`	integer	yes

Example

curl https://api.faxforagents.com/v1/policies/POLICY_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/policies/{policy_id}/versions`

Every version, oldest first

Parameters

GET /v1/policies/{policy_id}/versions parameters
Name	In	Type	Required	Notes
`policy_id`	path	string	yes

Responses

GET /v1/policies/{policy_id}/versions responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/policies/{policy_id}/versions response fields
Field	Type	Required	Description
`items`	array of object PolicyVersion	yes

Example

curl https://api.faxforagents.com/v1/policies/POLICY_ID/versions \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/policy-evaluations`

Dry run: would the calling key's policies allow this send? Never executes

Request body application/json, required

POST /v1/policy-evaluations request body
Field	Type	Required	Description
`document_id`	string or null	no	Or plan: this document ...
`from`	string or null	no
`quote_id`	string or null	no	Evaluate an existing quote.
`to`	string or null	no	... to this E.164 destination.

Responses

POST /v1/policy-evaluations responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/policy-evaluations response fields
Field	Type	Required
`decision`	string	yes
`denials`	array of object	yes
`executed`	boolean	no
`plan`	object	yes
`policy_id`	string or null	yes
`policy_name`	string or null	yes
`policy_version_id`	string or null	yes
`reason`	string	yes
`rule`	string or null	yes
`version`	integer or null	yes

Example

curl https://api.faxforagents.com/v1/policy-evaluations \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

sandbox

DELETE /v1/sandbox/data Reset this organization's test data
POST /v1/sandbox/inbound-faxes Create a synthetic inbound fax (the same pipeline as a real one)
GET /v1/sandbox/scenarios The scenario catalog and active fixtures
POST /v1/sandbox/scenarios Select the outcome of the next sends

DELETE `/v1/sandbox/data`

Reset this organization's test data

Responses

DELETE /v1/sandbox/data responses
Status	Meaning
`200`	Successful Response

Response fields

DELETE /v1/sandbox/data response fields
Field	Type	Required
`deleted`	object	yes
`reset`	boolean	yes
`wallet_available_micro`	integer	yes

Example

curl https://api.faxforagents.com/v1/sandbox/data \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/sandbox/inbound-faxes`

Create a synthetic inbound fax (the same pipeline as a real one)

A synthetic PDF goes through ``inbox.service.receive_now``: the private document, the inbox item, the ``fax.received`` event with its download reference, exactly as a carrier delivery (M8).

Request body application/json, required

POST /v1/sandbox/inbound-faxes request body
Field	Type	Required	Description
`from`	string or null	no
`pages`	integer	no
`partial_content`	boolean	no	Rehearse a cut-off transmission.
`to`	string	yes

Responses

POST /v1/sandbox/inbound-faxes responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/sandbox/inbound-faxes response fields
Field	Type	Required
`amount_micro`	integer	no
`document_id`	string or null	yes
`from`	string or null	no
`id`	string	yes
`note`	string or null	no
`pages`	integer	yes
`received_at`	string	yes
`status`	string	yes
`to`	string	yes

Example

curl https://api.faxforagents.com/v1/sandbox/inbound-faxes \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/sandbox/scenarios`

The scenario catalog and active fixtures

Responses

GET /v1/sandbox/scenarios responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/sandbox/scenarios response fields
Field	Type	Required
`destinations`	array of object	yes
`fixtures`	array of object SandboxFixture	yes
`scenarios`	array of object	yes

Example

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

POST `/v1/sandbox/scenarios`

Select the outcome of the next sends

Request body application/json, required

POST /v1/sandbox/scenarios request body
Field	Type	Required	Description
`destination`	string or null	no	Apply to one destination; omit for every send.
`scenario`	string	yes

Responses

POST /v1/sandbox/scenarios responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/sandbox/scenarios response fields
Field	Type	Required
`created_at`	string	yes
`destination`	string or null	yes
`expires_at`	string	yes
`id`	string	yes
`scenario`	string	yes

Example

curl https://api.faxforagents.com/v1/sandbox/scenarios \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

webhooks

GET /v1/webhook-deliveries Delivery attempts (no payload secrets)
POST /v1/webhook-deliveries/{delivery_id}/replay Replay the event with the same event id
GET /v1/webhooks List webhooks
POST /v1/webhooks Register a destination (secret shown once)
DELETE /v1/webhooks/{webhook_id} Remove a destination
PATCH /v1/webhooks/{webhook_id} Change url, filters or pause
POST /v1/webhooks/{webhook_id}/rotate-secret New secret; the old one signs too for 24 hours
POST /v1/webhooks/{webhook_id}/test Send a signed webhook.test event to this destination

GET `/v1/webhook-deliveries`

Delivery attempts (no payload secrets)

Parameters

GET /v1/webhook-deliveries parameters
Name	In	Type	Required	Notes
`webhook_id`	query	string or null	no
`event_id`	query	string or null	no
`cursor`	query	string or null	no
`limit`	query	integer	no	Default `50`.

Responses

GET /v1/webhook-deliveries responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

GET /v1/webhook-deliveries response fields
Field	Type	Required	Description
`items`	array of object Delivery	yes
`next_cursor`	string or null	no

Example

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

POST `/v1/webhook-deliveries/{delivery_id}/replay`

Replay the event with the same event id

Parameters

POST /v1/webhook-deliveries/{delivery_id}/replay parameters
Name	In	Type	Required	Notes
`delivery_id`	path	string	yes

Responses

POST /v1/webhook-deliveries/{delivery_id}/replay responses
Status	Meaning
`202`	Successful Response
`422`	Validation Error

Response fields

POST /v1/webhook-deliveries/{delivery_id}/replay response fields
Field	Type	Required
`attempt`	integer	yes
`created_at`	string	yes
`delivered_at`	string or null	yes
`duration_ms`	integer or null	yes
`error`	string or null	yes
`event_id`	string	yes
`event_type`	string	yes
`id`	string	yes
`next_attempt_at`	string or null	yes
`replay_of`	string or null	yes
`response_status`	integer or null	yes
`schedule_s`	array of integer	yes
`status`	string	yes
`webhook_id`	string	yes

Example

curl https://api.faxforagents.com/v1/webhook-deliveries/DELIVERY_ID/replay \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

GET `/v1/webhooks`

List webhooks

Responses

GET /v1/webhooks responses
Status	Meaning
`200`	Successful Response

Response fields

GET /v1/webhooks response fields
Field	Type	Required	Description
`items`	array of object Webhook	yes

Example

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

POST `/v1/webhooks`

Request body application/json, required

POST /v1/webhooks request body
Field	Type	Required	Description
`description`	string or null	no
`event_types`	array of string or null	no	Empty or omitted: every event type.
`url`	string	yes

Responses

POST /v1/webhooks responses
Status	Meaning
`201`	Successful Response
`422`	Validation Error

Response fields

POST /v1/webhooks response fields
Field	Type	Required	Description
`created_at`	string	yes
`description`	string or null	yes
`event_types`	array of string	yes
`id`	string	yes
`previous_secret_expires_at`	string or null	yes
`secret`	string	yes	whsec_... Shown once. Verify webhook-signature with it.
`status`	string	yes
`updated_at`	string	yes
`url`	string	yes

Example

curl https://api.faxforagents.com/v1/webhooks \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

DELETE `/v1/webhooks/{webhook_id}`

Remove a destination

Parameters

DELETE /v1/webhooks/{webhook_id} parameters
Name	In	Type	Required	Notes
`webhook_id`	path	string	yes

Responses

DELETE /v1/webhooks/{webhook_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

DELETE /v1/webhooks/{webhook_id} response fields
Field	Type	Required	Description
`deleted`	boolean	no
`id`	string	yes

Example

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID \
  -X DELETE \
  -H "Authorization: Bearer ffa_test_..."

PATCH `/v1/webhooks/{webhook_id}`

Change url, filters or pause

Parameters

PATCH /v1/webhooks/{webhook_id} parameters
Name	In	Type	Required	Notes
`webhook_id`	path	string	yes

Request body application/json, required

PATCH /v1/webhooks/{webhook_id} request body
Field	Type	Required
`description`	string or null	no
`event_types`	array of string or null	no
`status`	string (active, paused) or null	no
`url`	string or null	no

Responses

PATCH /v1/webhooks/{webhook_id} responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

PATCH /v1/webhooks/{webhook_id} response fields
Field	Type	Required
`created_at`	string	yes
`description`	string or null	yes
`event_types`	array of string	yes
`id`	string	yes
`previous_secret_expires_at`	string or null	yes
`status`	string	yes
`updated_at`	string	yes
`url`	string	yes

Example

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID \
  -X PATCH \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/webhooks/{webhook_id}/rotate-secret`

New secret; the old one signs too for 24 hours

Parameters

POST /v1/webhooks/{webhook_id}/rotate-secret parameters
Name	In	Type	Required	Notes
`webhook_id`	path	string	yes

Responses

POST /v1/webhooks/{webhook_id}/rotate-secret responses
Status	Meaning
`200`	Successful Response
`422`	Validation Error

Response fields

POST /v1/webhooks/{webhook_id}/rotate-secret response fields
Field	Type	Required	Description
`created_at`	string	yes
`description`	string or null	yes
`event_types`	array of string	yes
`id`	string	yes
`previous_secret_expires_at`	string or null	yes
`secret`	string	yes	whsec_... Shown once. Verify webhook-signature with it.
`status`	string	yes
`updated_at`	string	yes
`url`	string	yes

Example

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID/rotate-secret \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

POST `/v1/webhooks/{webhook_id}/test`

Send a signed webhook.test event to this destination

Parameters

POST /v1/webhooks/{webhook_id}/test parameters
Name	In	Type	Required	Notes
`webhook_id`	path	string	yes

Responses

POST /v1/webhooks/{webhook_id}/test responses
Status	Meaning
`202`	Successful Response
`422`	Validation Error

Response fields

POST /v1/webhooks/{webhook_id}/test response fields
Field	Type	Required
`correlation_id`	string or null	yes
`created_at`	string	yes
`data`	object	yes
`environment`	string (live, test)	yes
`fax_job_id`	string or null	yes
`id`	string	yes
`org_id`	string	yes
`project_id`	string or null	yes
`resource_id`	string	yes
`resource_type`	string	yes
`schema_version`	integer	yes
`type`	string	yes

Example

curl https://api.faxforagents.com/v1/webhooks/WEBHOOK_ID/test \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

Schemas

147 named objects, as the API sends and accepts them.

Accepted

Accepted fields
Field	Type	Required	Description
`organization`	object OrganizationSummary	yes

Agent

Agent fields
Field	Type	Required
`budget_id`	string or null	yes
`budgets`	array of object	yes
`contact_email`	string or null	yes
`created_at`	string	yes
`created_by`	string	yes
`disabled_at`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`keys`	array of object ApiKey	yes
`name`	string	yes
`policy_ids`	array of string	yes
`project_id`	string or null	yes
`purpose`	string or null	yes
`status`	string	yes
`updated_at`	string	yes

AgentActivity

AgentActivity fields
Field	Type	Required
`action`	string	yes
`actor`	string	yes
`correlation_id`	string or null	yes
`created_at`	string	yes
`data`	object	yes
`id`	string	yes
`resource_id`	string or null	yes
`resource_type`	string	yes

AgentActivityPage

AgentActivityPage fields
Field	Type	Required	Description
`items`	array of object AgentActivity	yes
`next_cursor`	string or null	no

AgentCreate

AgentCreate fields
Field	Type	Required	Description
`contact_email`	string or null	no	Where decided approvals are mailed.
`name`	string	yes
`policy_ids`	array of string	no
`purpose`	string or null	no	Shown to humans, never evaluated.

AgentKeyCreate

AgentKeyCreate fields
Field	Type	Required	Description
`environment`	string (live, test)	no
`expires_in_days`	integer or null	no
`label`	string	no
`scopes`	array of string or null	no	Omit for the default agent set. Never approval:decide, key:admin, policy:admin, agent:admin.

AgentList

AgentList fields
Field	Type	Required	Description
`items`	array of object Agent	yes

AgentUpdate

AgentUpdate fields
Field	Type	Required	Description
`contact_email`	string or null	no
`enabled`	boolean or null	no	false revokes every key of the agent.
`name`	string or null	no
`policy_ids`	array of string or null	no
`purpose`	string or null	no

ApiKey

ApiKey fields
Field	Type	Required
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`id`	string	yes
`label`	string	yes
`last_used_at`	string or null	yes
`prefix`	string	yes
`project_id`	string or null	yes
`revoked_at`	string or null	yes
`rotated_from_id`	string or null	yes
`scopes`	array of string	yes

ApiKeyCreate

ApiKeyCreate fields
Field	Type	Required	Description
`environment`	string (live, test)	no
`expires_in_days`	integer or null	no
`label`	string	yes
`scopes`	array of string or null	no	Omit for the default agent set; '*' for all.

ApiKeyList

ApiKeyList fields
Field	Type	Required	Description
`items`	array of object ApiKey	yes

ApiKeyWithSecret

ApiKeyWithSecret fields
Field	Type	Required	Description
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`id`	string	yes
`label`	string	yes
`last_used_at`	string or null	yes
`prefix`	string	yes
`project_id`	string or null	yes
`revoked_at`	string or null	yes
`rotated_from_id`	string or null	yes
`scopes`	array of string	yes
`secret`	string	yes	Shown once. Store it now; it cannot be read back.

ApprovalDecision

ApprovalDecision fields
Field	Type	Required	Description
`reason`	string or null	no

ApprovalRequest

ApprovalRequest fields
Field	Type	Required	Description
`bound`	object	yes
`consumed_by_job_id`	string or null	yes
`created_at`	string	yes
`decided_at`	string or null	yes
`decided_by`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (send, help)	yes
`message`	string or null	yes
`notified`	boolean or null	no	On creation: whether the organization was mailed. false when the request repeats a pending one or the organization's daily cap of request mails is reached; the request is still shown in the dashboard.
`quote_id`	string or null	yes
`reason`	string or null	yes
`requested_by`	string	yes
`status`	string (pending, approved, rejected, revoked, expired)	yes

ApprovalRequestCreate

ApprovalRequestCreate fields
Field	Type	Required	Description
`fax_job_id`	string or null	no
`kind`	string (send, help)	no
`message`	string or null	no	What the person should know (kind help). Shown as data.
`quote_id`	string or null	no	The quote to bind (kind send).

ApprovalRequestPage

ApprovalRequestPage fields
Field	Type	Required	Description
`items`	array of object ApprovalRequest	yes
`next_cursor`	string or null	no

Attempt

Attempt fields
Field	Type	Required
`attempt_number`	integer	yes
`error`	string or null	yes
`evidence`	object or null	yes
`failure_code`	string or null	yes
`fax_job_id`	string	yes
`finished_at`	string or null	yes
`id`	string	yes
`pages_sent`	integer	yes
`provider`	string	yes
`provider_ref`	string or null	yes
`started_at`	string	yes
`status`	string	yes

AttemptPage

AttemptPage fields
Field	Type	Required	Description
`items`	array of object Attempt	yes

AutoTopup

AutoTopup fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`created_at`	string	yes
`daily_cap_micro`	integer	yes
`disabled_at`	string or null	yes
`environment`	string (live, test)	yes
`id`	string	yes
`last_attempt_at`	string or null	yes
`payment_method_saved`	boolean	yes
`setup_session_id`	string or null	yes
`setup_url`	string or null	no	Where to save the card while status is pending_setup.
`status`	string (pending_setup, active, disabled)	yes
`threshold_micro`	integer	yes
`updated_at`	string	yes

AutoTopupCreate

AutoTopupCreate fields
Field	Type	Required	Description
`amount_micro`	integer	yes	Whole dollars, 10 to 1000 USD.
`daily_cap_micro`	integer	yes	Never more than this per UTC day.
`threshold_micro`	integer	yes	Top up when the available balance drops below this.

AutoTopupList

AutoTopupList fields
Field	Type	Required	Description
`items`	array of object AutoTopup	yes

Balance

Balance fields
Field	Type	Required
`available_micro`	integer	yes
`currency`	string	yes
`environment`	string (live, test)	yes
`held_micro`	integer	yes

BillingSettings

BillingSettings fields
Field	Type	Required
`billing_email`	string or null	yes
`disputed`	boolean	yes
`low_balance_active`	boolean	yes
`low_balance_threshold_micro`	integer	yes
`org_id`	string	yes
`stripe_customer`	boolean	yes
`workspace`	boolean	yes

BillingSettingsPatch

BillingSettingsPatch fields
Field	Type	Required	Description
`billing_email`	string or null	no
`low_balance_threshold_micro`	integer or null	no

Budget

Budget fields
Field	Type	Required
`agent_id`	string or null	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`id`	string	yes
`limit_micro`	integer	yes
`period`	string (daily, monthly)	yes
`project_id`	string or null	yes
`remaining_micro`	integer	yes
`resets_at`	string	yes
`scope`	string (organization, project, agent)	yes
`spent_micro`	integer	yes
`status`	string (active, disabled)	yes
`updated_at`	string	yes

BudgetCreate

BudgetCreate fields
Field	Type	Required
`agent_id`	string or null	no
`limit_micro`	integer	yes
`period`	string (daily, monthly)	yes
`project_id`	string or null	no
`scope`	string (organization, project, agent)	no

BudgetList

BudgetList fields
Field	Type	Required	Description
`items`	array of object Budget	yes

BudgetPatch

BudgetPatch fields
Field	Type	Required	Description
`limit_micro`	integer or null	no
`status`	string (active, disabled) or null	no

Capabilities

Capabilities fields
Field	Type	Required
`approvals`	boolean	yes
`environment`	string (live, test)	yes
`formats`	array of string	yes
`limits`	object	yes
`max_pages`	integer	yes
`max_upload_bytes`	integer	yes
`numbers`	boolean	yes
`price_version`	string	yes
`provider`	string	yes
`rates`	object	yes
`receive`	boolean	yes
`routes`	array of string	yes
`scopes`	array of string	yes
`send`	boolean	yes

ClassificationCreate

ClassificationCreate fields
Field	Type	Required	Description
`abstain_below`	number	no
`document_id`	string or null	no
`document_types`	array of string	yes
`inbox_item_id`	string or null	no
`max_pages`	integer or null	no
`strict`	boolean	no	Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning.
`strong_model_if_below`	number	no

Correction

Correction fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`extraction_id`	string	yes
`field`	string	yes
`id`	string	yes
`note`	string or null	yes
`value`	any	yes

CorrectionCreate

CorrectionCreate fields
Field	Type	Required
`field`	string or null	no
`note`	string or null	no
`value`	any	no

Coverage

Coverage 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

Deleted

Deleted fields
Field	Type	Required	Description
`deleted`	boolean	no
`id`	string	yes

Delivery

Delivery fields
Field	Type	Required
`attempt`	integer	yes
`created_at`	string	yes
`delivered_at`	string or null	yes
`duration_ms`	integer or null	yes
`error`	string or null	yes
`event_id`	string	yes
`event_type`	string	yes
`id`	string	yes
`next_attempt_at`	string or null	yes
`replay_of`	string or null	yes
`response_status`	integer or null	yes
`schedule_s`	array of integer	yes
`status`	string	yes
`webhook_id`	string	yes

DeliveryPage

DeliveryPage fields
Field	Type	Required	Description
`items`	array of object Delivery	yes
`next_cursor`	string or null	no

Document

Document fields
Field	Type	Required
`content_type`	string	yes
`created_at`	string	yes
`deleted_at`	string or null	yes
`environment`	string (live, test)	yes
`expires_at`	string or null	yes
`filename`	string	yes
`id`	string	yes
`page_count`	integer	yes
`render_reason`	string or null	yes
`render_status`	string	yes
`sha256`	string	yes
`size_bytes`	integer	yes
`source`	string	yes
`status`	string	yes
`upload_id`	string or null	yes
`validation`	object	yes

DocumentCreate

DocumentCreate fields
Field	Type	Required	Description
`filename`	string or null	no
`html`	string or null	no	HTML rendered to PDF by a headless browser with scripts off and no network: inline CSS and data: images print, external resources are counted as blocked. US letter unless @page says otherwise. At most 2 MiB.
`markdown`	string or null	no	Markdown (headings, lists, emphasis, code) rendered to PDF.
`text`	string or null	no	Plain text rendered to a letter PDF.
`upload_id`	string or null	no

DocumentPage

DocumentPage fields
Field	Type	Required	Description
`items`	array of object Document	yes
`next_cursor`	string or null	no

DocumentPages

DocumentPages fields
Field	Type	Required
`document_id`	string	yes
`items`	array of object PagePreview	yes
`page_count`	integer	yes
`render_reason`	string or null	yes
`render_status`	string	yes

DocumentValidation

DocumentValidation fields
Field	Type	Required
`id`	string	yes
`page_count`	integer	yes
`render_reason`	string or null	yes
`render_status`	string	yes
`status`	string	yes
`warnings`	array of object	yes

EffectivePolicies

EffectivePolicies fields
Field	Type	Required
`actor`	string	yes
`approval_required_without_policy`	boolean	yes
`environment`	string (live, test)	yes
`policies`	array of object Policy	yes
`rules_order`	array of string	yes
`under_policy`	boolean	yes

Event

Event fields
Field	Type	Required
`correlation_id`	string or null	yes
`created_at`	string	yes
`data`	object	yes
`environment`	string (live, test)	yes
`fax_job_id`	string or null	yes
`id`	string	yes
`org_id`	string	yes
`project_id`	string or null	yes
`resource_id`	string	yes
`resource_type`	string	yes
`schema_version`	integer	yes
`type`	string	yes

EventPage

EventPage fields
Field	Type	Required	Description
`items`	array of object Event	yes
`next_cursor`	string or null	no

Extraction

Extraction fields
Field	Type	Required	Description
`completed_at`	string or null	yes
`confidence`	number or null	yes
`corrections`	array of object or null	no
`created_at`	string	yes
`created_by`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes	The document's page count. Above pages_processed on a completed row means the cap left pages unread; output.truncated and a warning say so.
`environment`	string (live, test)	yes
`error_code`	string or null	yes
`id`	string	yes
`inbox_item_id`	string or null	yes
`kind`	string (extract, classify, summarize)	yes
`models`	object	yes
`options`	object	yes
`output`	object or null	yes
`pages`	array of object ExtractionPage	yes
`pages_escalated`	integer	yes
`pages_processed`	integer	yes
`pages_requested`	integer	yes
`price_micro`	integer	yes
`provider_cost_micro`	integer	yes
`schema`	object or null	no
`schema_id`	string or null	yes
`started_at`	string or null	yes
`status`	string (pending, queued, running, completed, failed)	yes

ExtractionCreate

ExtractionCreate fields
Field	Type	Required	Description
`document_id`	string or null	no
`inbox_item_id`	string or null	no
`max_pages`	integer or null	no
`schema`	object or null	no	A JSON Schema object of string, number, boolean or date fields with descriptions.
`schema_id`	string or null	no
`strict`	boolean	no	Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning.
`strong_model_if_below`	number	no

ExtractionPage

ExtractionPage fields
Field	Type	Required
`confidence`	number	yes
`escalated`	boolean	no
`language`	string or null	no
`model`	string	yes
`page`	integer	yes
`status`	string	yes
`text`	string	yes
`warnings`	array of string	no

ExtractionPageList

ExtractionPageList fields
Field	Type	Required	Description
`items`	array of object Extraction	yes
`next_cursor`	string or null	no

ExtractionSchema

ExtractionSchema fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`description`	string or null	yes
`id`	string	yes
`name`	string	yes
`schema`	object	yes
`status`	string	yes
`version`	integer	yes

ExtractionSchemaList

ExtractionSchemaList fields
Field	Type	Required	Description
`items`	array of object ExtractionSchema	yes

FaxCreate

M9: an approved request authorizes the send; without one a quote that needs authorization is evaluated against the caller's delegated policies.

FaxCreate fields
Field	Type	Required	Description
`approval_id`	string or null	no	An approved approval request bound to this quote. Consumed by this one send.
`client_reference`	string or null	no
`quote_id`	string	yes

FaxJob

FaxJob fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`attempt_count`	integer	yes
`billable_pages`	integer	yes
`cancel_requested_at`	string or null	yes
`captured_micro`	integer	yes
`client_reference`	string or null	yes
`completed_at`	string or null	yes
`cover_pages`	integer	yes
`created_at`	string	yes
`currency`	string	yes
`direction`	string	yes
`document_id`	string	yes
`document_sha256`	string	yes
`environment`	string (live, test)	yes
`evidence`	object or null	no	The carrier's evidence once delivered or partial; null before.
`failure_code`	string or null	yes
`from`	string or null	no
`id`	string	yes
`pages_sent`	integer	yes
`provider`	string	yes
`provider_ref`	string or null	yes
`quote_id`	string or null	yes
`route`	string	yes
`state`	string (queued, active, partial, failed, unknown, delivered)	yes
`to`	string	yes
`transmitted_sha256`	string or null	yes
`updated_at`	string	yes

FaxJobPage

FaxJobPage fields
Field	Type	Required	Description
`items`	array of object FaxJob	yes
`next_cursor`	string or null	no

HTTPValidationError

HTTPValidationError fields
Field	Type	Required	Description
`detail`	array of object ValidationError	no

InboxItemDetail

InboxItemDetail fields
Field	Type	Required
`amount_micro`	integer	no
`document`	object or null	no
`document_id`	string or null	yes
`duration_secs`	integer or null	no
`environment`	string (live, test)	no
`expires_at`	string or null	no
`extraction_id`	string or null	no
`from`	string or null	no
`id`	string	yes
`media_status`	string	no
`note`	string or null	no
`number_id`	string or null	no
`pages`	integer	yes
`partial_content`	boolean	no
`project_id`	string or null	no
`provider`	string	no
`read_at`	string or null	no
`received_at`	string	yes
`status`	string	yes
`text`	string or null	no
`to`	string	yes

InboxPage

InboxPage fields
Field	Type	Required	Description
`items`	array of object faxforagents__api__routes__inbox__InboxItem	yes
`next_cursor`	string or null	no

InboxUpdate

InboxUpdate fields
Field	Type	Required	Description
`status`	string (received, read, archived) or null	no

Inventory

Inventory 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

InventoryNumber

InventoryNumber fields
Field	Type	Required
`country`	string	yes
`currency`	string	yes
`e164`	string	yes
`locality`	string or null	yes
`monthly_micro`	integer	yes
`number_type`	string	yes
`setup_micro`	integer	yes

Invitation

Invitation fields
Field	Type	Required
`accepted_at`	string or null	yes
`created_at`	string	yes
`email`	string	yes
`expires_at`	string	yes
`id`	string	yes
`invited_by`	string	yes
`role`	string (owner, admin, member, viewer)	yes

InvitationCreate

InvitationCreate fields
Field	Type	Required	Description
`email`	string (email)	yes
`role`	string (owner, admin, member, viewer)	no

InvitationList

InvitationList fields
Field	Type	Required	Description
`items`	array of object Invitation	yes

Invoice

Invoice fields
Field	Type	Required
`amount_due_micro`	integer	yes
`amount_paid_micro`	integer	yes
`created_at`	string or null	yes
`currency`	string	yes
`hosted_invoice_url`	string or null	yes
`id`	string	yes
`invoice_pdf`	string or null	yes
`number`	string or null	yes
`status`	string or null	yes
`subscription_id`	string or null	yes

InvoicePage

InvoicePage fields
Field	Type	Required	Description
`items`	array of object Invoice	yes
`next_cursor`	string or null	no

LedgerEntry

LedgerEntry fields
Field	Type	Required
`account`	string	yes
`amount_micro`	integer	yes
`created_at`	string	yes
`id`	string	yes
`kind`	string	yes
`memo`	string or null	yes
`ref_id`	string or null	yes
`ref_type`	string or null	yes
`txn_id`	string	yes

LedgerPage

LedgerPage fields
Field	Type	Required	Description
`items`	array of object LedgerEntry	yes
`next_cursor`	string or null	no

MagicLinkRequest

MagicLinkRequest fields
Field	Type	Required	Description
`email`	string (email)	yes
`next`	string or null	no	An in-app path to open after sign-in.

Member

Member fields
Field	Type	Required
`created_at`	string	yes
`email`	string	yes
`id`	string	yes
`name`	string or null	yes
`role`	string (owner, admin, member, viewer)	yes
`user_id`	string or null	yes

MemberList

MemberList fields
Field	Type	Required	Description
`items`	array of object Member	yes

MemberPatch

MemberPatch fields
Field	Type	Required	Description
`role`	string (owner, admin, member, viewer) or null	no	Required. Optional in the schema so a foreign id is a 404 first.

Number

Number fields
Field	Type	Required
`activated_at`	string or null	yes
`country`	string	yes
`created_at`	string	yes
`currency`	string	yes
`e164`	string	yes
`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

NumberList

NumberList fields
Field	Type	Required	Description
`items`	array of object Number	yes

NumberOrder

NumberOrder 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

NumberOrderCreate

NumberOrderCreate fields
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.

NumberUpdate

NumberUpdate fields
Field	Type	Required
`inbound_webhook_id`	string or null	no
`label`	string or null	no
`project_id`	string or null	no

Organization

Organization fields
Field	Type	Required
`created_at`	string	yes
`id`	string	yes
`members`	integer	yes
`name`	string	yes
`role`	string (owner, admin, member, viewer) or null	yes

OrganizationList

OrganizationList fields
Field	Type	Required	Description
`items`	array of object OrganizationSummary	yes

OrganizationPatch

OrganizationPatch fields
Field	Type	Required	Description
`name`	string	yes

OrganizationSummary

OrganizationSummary fields
Field	Type	Required
`id`	string	yes
`name`	string	yes
`role`	string (owner, admin, member, viewer)	yes

PagePreview

PagePreview fields
Field	Type	Required
`height_px`	integer or null	yes
`page_number`	integer	yes
`url`	string	yes
`width_px`	integer or null	yes

Passkey

Passkey fields
Field	Type	Required
`aaguid`	string or null	yes
`backup_eligible`	boolean	yes
`created_at`	string	yes
`id`	string	yes
`label`	string or null	yes
`last_used_at`	string or null	yes
`transports`	array of string or null	yes

PasskeyList

PasskeyList fields
Field	Type	Required	Description
`items`	array of object Passkey	yes

PasskeyLoginVerify

PasskeyLoginVerify fields
Field	Type	Required	Description
`credential`	object	yes

PasskeyRegisterVerify

PasskeyRegisterVerify fields
Field	Type	Required	Description
`credential`	object	yes
`label`	string or null	no

Policy

Policy fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`current_version_id`	string or null	yes
`enabled`	boolean	yes
`id`	string	yes
`name`	string	yes
`purpose`	string or null	yes
`rules`	object	yes
`updated_at`	string	yes
`version`	integer	yes

PolicyCreate

PolicyCreate fields
Field	Type	Required	Description
`enabled`	boolean	no
`name`	string	yes
`purpose`	string or null	no	Why this policy exists. Shown, never evaluated.
`rules`	object	yes	See the PolicyRules schema in docs/APPROVALS.md.

PolicyEvaluation

PolicyEvaluation fields
Field	Type	Required
`decision`	string	yes
`denials`	array of object	yes
`executed`	boolean	no
`plan`	object	yes
`policy_id`	string or null	yes
`policy_name`	string or null	yes
`policy_version_id`	string or null	yes
`reason`	string	yes
`rule`	string or null	yes
`version`	integer or null	yes

PolicyEvaluationCreate

PolicyEvaluationCreate fields
Field	Type	Required	Description
`document_id`	string or null	no	Or plan: this document ...
`from`	string or null	no
`quote_id`	string or null	no	Evaluate an existing quote.
`to`	string or null	no	... to this E.164 destination.

PolicyList

PolicyList fields
Field	Type	Required	Description
`items`	array of object Policy	yes

PolicyUpdate

PolicyUpdate fields
Field	Type	Required
`enabled`	boolean or null	no
`name`	string or null	no
`purpose`	string or null	no
`rules`	object or null	no

PolicyVersion

PolicyVersion fields
Field	Type	Required
`created_at`	string	yes
`created_by`	string	yes
`enabled`	boolean	yes
`id`	string	yes
`name`	string	yes
`policy_id`	string	yes
`purpose`	string or null	yes
`rules`	object	yes
`version`	integer	yes

PolicyVersionList

PolicyVersionList fields
Field	Type	Required	Description
`items`	array of object PolicyVersion	yes

PortOrder

PortOrder 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

PortOrderCreate

PortOrderCreate fields
Field	Type	Required	Description
`note`	string or null	no
`numbers`	array of string	yes

PortOrderList

PortOrderList fields
Field	Type	Required	Description
`items`	array of object PortOrder	yes

PortOutRequestCreate

PortOutRequestCreate fields
Field	Type	Required	Description
`note`	string or null	no
`number_id`	string	yes

PortabilityCheck

PortabilityCheck fields
Field	Type	Required	Description
`checked_at`	string	yes
`items`	array of object	yes

PortabilityCheckCreate

PortabilityCheckCreate fields
Field	Type	Required	Description
`numbers`	array of string	yes

PortalSession

PortalSession fields
Field	Type	Required	Description
`expires_at`	string	yes
`url`	string	yes

Providers

Providers fields
Field	Type	Required
`github`	boolean	yes
`google`	boolean	yes
`magic_link`	boolean	no
`passkeys`	boolean	no

Quote

Quote fields
Field	Type	Required
`amount_micro`	integer	yes
`authorization_required`	boolean	yes
`billable_pages`	integer	yes
`consumed_by_job_id`	string or null	yes
`cover`	object or null	yes
`cover_pages`	integer	yes
`created_at`	string	yes
`currency`	string	yes
`document_id`	string	yes
`document_pages`	integer	yes
`document_sha256`	string	yes
`environment`	string (live, test)	yes
`expired`	boolean	yes
`expires_at`	string	yes
`from`	string or null	no
`id`	string	yes
`per_page_micro`	integer	no
`price_version`	string	yes
`route`	string	yes
`route_label`	string	no
`to`	string	yes
`warnings`	array of object	yes

QuoteCreate

QuoteCreate fields
Field	Type	Required	Description
`cover`	object or null	no	Cover sheet fields: to_name, from_name, subject, message. Counts as a page.
`document_id`	string	yes
`from`	string or null	no	A number you own; omit for the shared pool.
`to`	string	yes	Destination in E.164, for example +12025550123.

Reauth

Reauth fields
Field	Type	Required	Description
`credential`	object or null	no
`method`	string (passkey, magic_link)	yes

Receipt

Receipt fields
Field	Type	Required
`amount_micro`	integer	yes
`attempts`	array of object Attempt	yes
`billable_pages`	integer	yes
`captured_micro`	integer	yes
`completed_at`	string or null	yes
`created_at`	string	yes
`currency`	string	yes
`document_sha256`	string	yes
`evidence`	object or null	yes
`failure_code`	string or null	yes
`fax_job_id`	string	yes
`from`	string or null	no
`generated_at`	string	yes
`note`	string	yes
`pages_sent`	integer	yes
`provider`	string	yes
`state`	string	yes
`to`	string	yes
`transmitted_sha256`	string or null	yes

ReleaseRequest

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

Requested

Requested fields
Field	Type	Required
`kind`	string (export, deletion)	yes
`message`	string	yes
`requested`	boolean	yes

Revoked

Revoked fields
Field	Type	Required	Description
`revoked`	integer	yes

SandboxFixture

SandboxFixture fields
Field	Type	Required
`created_at`	string	yes
`destination`	string or null	yes
`expires_at`	string	yes
`id`	string	yes
`scenario`	string	yes

SandboxInboundCreate

SandboxInboundCreate fields
Field	Type	Required	Description
`from`	string or null	no
`pages`	integer	no
`partial_content`	boolean	no	Rehearse a cut-off transmission.
`to`	string	yes

SandboxReset

SandboxReset fields
Field	Type	Required
`deleted`	object	yes
`reset`	boolean	yes
`wallet_available_micro`	integer	yes

SandboxScenarioCreate

SandboxScenarioCreate fields
Field	Type	Required	Description
`destination`	string or null	no	Apply to one destination; omit for every send.
`scenario`	string	yes

SandboxScenarios

SandboxScenarios fields
Field	Type	Required
`destinations`	array of object	yes
`fixtures`	array of object SandboxFixture	yes
`scenarios`	array of object	yes

SchemaCreate

SchemaCreate fields
Field	Type	Required
`description`	string or null	no
`name`	string	yes
`schema`	object	yes

SenderVerification

SenderVerification 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

SenderVerificationCreate

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

Sent

Sent fields
Field	Type	Required	Description
`message`	string	yes
`sent`	boolean	yes

ServiceStatus

ServiceStatus fields
Field	Type	Required
`database`	boolean	yes
`environment`	string (live, test)	yes
`provider`	string	yes
`status`	string (ok, degraded)	yes
`status_page`	string or null	no
`version`	string	yes
`worker_beat_age_s`	integer or null	no

SessionInfo

SessionInfo fields
Field	Type	Required
`auth_method`	string	yes
`authenticated_at`	string	yes
`expires_at`	string	yes
`fresh`	boolean	yes
`fresh_until`	string	yes
`id`	string	yes

SessionList

SessionList fields
Field	Type	Required	Description
`items`	array of object SessionOut	yes

SessionOut

SessionOut fields
Field	Type	Required
`auth_method`	string	yes
`authenticated_at`	string	yes
`created_at`	string	yes
`current`	boolean	yes
`expires_at`	string	yes
`id`	string	yes
`ip`	string or null	yes
`last_seen_at`	string	yes
`user_agent`	string or null	yes

SignedUrl

SignedUrl fields
Field	Type	Required
`content_type`	string	yes
`expires_at`	string	yes
`url`	string	yes

Subscription

Subscription fields
Field	Type	Required
`cancel_at_period_end`	boolean	yes
`canceled_at`	string or null	yes
`created_at`	string	yes
`current_period_end`	string or null	yes
`entitled`	boolean	yes
`id`	string	yes
`product`	string	yes
`status`	string	yes
`stripe_price_id`	string or null	yes
`stripe_subscription_id`	string	yes
`updated_at`	string	yes

SubscriptionCheckout

SubscriptionCheckout fields
Field	Type	Required
`product`	string	yes
`stripe_session_id`	string	yes
`url`	string	yes

SubscriptionList

SubscriptionList fields
Field	Type	Required
`items`	array of object Subscription	yes
`next_cursor`	string or null	no
`workspace`	boolean	yes

SummaryCreate

SummaryCreate fields
Field	Type	Required	Description
`document_id`	string or null	no
`inbox_item_id`	string or null	no
`max_pages`	integer or null	no
`strict`	boolean	no	Refuse with page_limit_exceeded when the document has more pages than would be read, instead of reading the first ones and warning.
`strong_model_if_below`	number	no

SwitchOrganization

SwitchOrganization fields
Field	Type	Required	Description
`org_id`	string	yes

TopupCreate

TopupCreate fields
Field	Type	Required	Description
`amount_usd`	integer	yes	Whole US dollars, 10 to 1000 per session.

TopupSession

TopupSession fields
Field	Type	Required	Description
`amount_micro`	integer	yes
`auto_topup_id`	string or null	yes
`completed_at`	string or null	yes
`created_at`	string	yes
`currency`	string	yes
`environment`	string (live, test)	yes
`error`	string or null	yes
`expires_at`	string or null	yes
`id`	string	yes
`kind`	string (manual, auto, setup)	yes
`status`	string (open, completed, expired, canceled, failed)	yes
`stripe_payment_intent_id`	string or null	yes
`stripe_session_id`	string or null	yes
`url`	string or null	no	The hosted Checkout page while the session is open.

TopupSessionPage

TopupSessionPage fields
Field	Type	Required	Description
`items`	array of object TopupSession	yes
`next_cursor`	string or null	no

UploadComplete

UploadComplete fields
Field	Type	Required	Description
`sha256`	string or null	no	Optional: fail if the bytes differ.

UploadCreate

UploadCreate fields
Field	Type	Required	Description
`content_type`	string	no	application/pdf, image/png, image/jpeg or image/tiff. An image becomes 8-bit gray letter pages, since fax is monochrome. A frame wider than it is tall is rotated. A frame above 300 dpi letter is downsampled. Every TIFF frame is a page. PNG and JPEG take the first frame. The bytes must be the declared type.
`filename`	string	yes
`size_bytes`	integer	yes

UploadSession

UploadSession fields
Field	Type	Required
`completed_at`	string or null	yes
`content_type`	string	yes
`created_at`	string	yes
`declared_size`	integer	yes
`expires_at`	string	yes
`filename`	string	yes
`id`	string	yes
`received_size`	integer	yes
`sha256`	string or null	yes
`status`	string	yes
`upload_method`	string or null	no
`upload_url`	string or null	no
`upload_url_expires_at`	string or null	no

UsageExport

UsageExport fields
Field	Type	Required
`content_type`	string	yes
`created_at`	string	yes
`environment`	string (live, test)	yes
`expires_at`	string	yes
`id`	string	yes
`params`	object	yes
`row_count`	integer	yes
`status`	string (ready, expired)	yes
`url`	string or null	yes

UsageExportCreate

UsageExportCreate fields
Field	Type	Required	Description
`from`	string or null	no	ISO date; default 30 days ago.
`to`	string or null	no	ISO date; default today.

UsageItem

UsageItem fields
Field	Type	Required
`amount_micro`	integer	yes
`day`	string or null	no
`destination`	string or null	no
`direction`	string or null	no
`jobs`	integer	yes
`pages`	integer	yes
`project_id`	string or null	no
`route`	string or null	no

UsageReport

UsageReport fields
Field	Type	Required
`currency`	string	yes
`environment`	string (live, test)	yes
`from`	string	yes
`group_by`	array of string	yes
`items`	array of object UsageItem	yes
`to`	string	yes
`totals`	object	yes

UserOut

UserOut fields
Field	Type	Required
`created_at`	string	yes
`email`	string	yes
`email_verified`	boolean	yes
`id`	string	yes
`last_login_at`	string or null	yes
`name`	string or null	yes

ValidationError

ValidationError fields
Field	Type	Required
`ctx`	object	no
`input`	any	no
`loc`	array of string or integer	yes
`msg`	string	yes
`type`	string	yes

Webhook

Webhook fields
Field	Type	Required
`created_at`	string	yes
`description`	string or null	yes
`event_types`	array of string	yes
`id`	string	yes
`previous_secret_expires_at`	string or null	yes
`status`	string	yes
`updated_at`	string	yes
`url`	string	yes

WebhookCreate

WebhookCreate fields
Field	Type	Required	Description
`description`	string or null	no
`event_types`	array of string or null	no	Empty or omitted: every event type.
`url`	string	yes

WebhookList

WebhookList fields
Field	Type	Required	Description
`items`	array of object Webhook	yes

WebhookUpdate

WebhookUpdate fields
Field	Type	Required
`description`	string or null	no
`event_types`	array of string or null	no
`status`	string (active, paused) or null	no
`url`	string or null	no

WebhookWithSecret

WebhookWithSecret fields
Field	Type	Required	Description
`created_at`	string	yes
`description`	string or null	yes
`event_types`	array of string	yes
`id`	string	yes
`previous_secret_expires_at`	string or null	yes
`secret`	string	yes	whsec_... Shown once. Verify webhook-signature with it.
`status`	string	yes
`updated_at`	string	yes
`url`	string	yes

faxforagentsapiroutesinboxInboxItem

faxforagents__api__routes__inbox__InboxItem fields
Field	Type	Required
`amount_micro`	integer	no
`document_id`	string or null	yes
`duration_secs`	integer or null	no
`environment`	string (live, test)	no
`expires_at`	string or null	no
`from`	string or null	no
`id`	string	yes
`media_status`	string	no
`note`	string or null	no
`number_id`	string or null	no
`pages`	integer	yes
`partial_content`	boolean	no
`project_id`	string or null	no
`provider`	string	no
`read_at`	string or null	no
`received_at`	string	yes
`status`	string	yes
`to`	string	yes

faxforagentsapischemas__InboxItem

faxforagents__api__schemas__InboxItem fields
Field	Type	Required
`amount_micro`	integer	no
`document_id`	string or null	yes
`from`	string or null	no
`id`	string	yes
`note`	string or null	no
`pages`	integer	yes
`received_at`	string	yes
`status`	string	yes
`to`	string	yes

faxforagentsapischemas__Me

faxforagents__api__schemas__Me fields
Field	Type	Required
`actor`	string	yes
`environment`	string (live, test)	yes
`key_id`	string	yes
`key_prefix`	string	yes
`org_id`	string	yes
`project_id`	string	yes
`scopes`	array of string	yes

faxforagentsauthschemas__Me

faxforagents__auth__schemas__Me fields
Field	Type	Required
`csrf_token`	string	yes
`organization`	object OrganizationSummary or null	yes
`organizations`	array of object OrganizationSummary	yes
`passkeys`	integer	yes
`providers`	object Providers	yes
`session`	object SessionInfo	yes
`user`	object UserOut	yes

Full API reference

agents

GET /v1/agents

Responses

Response fields

Example

POST /v1/agents

Request body application/json, required

Responses

Response fields

Example

GET /v1/agents/{agent_id}

Parameters

Responses

Response fields

Example

PATCH /v1/agents/{agent_id}

Parameters

Request body application/json, required

Responses

Response fields

Example

GET /v1/agents/{agent_id}/activity

Parameters

Responses

Response fields

Example

POST /v1/agents/{agent_id}/keys

Parameters

Request body application/json, required

Responses

Response fields

Example

identity

GET /v1/api-keys

Responses

Response fields

Example

POST /v1/api-keys

Request body application/json, required

Responses

Response fields

Example

DELETE /v1/api-keys/{key_id}

Parameters

Responses

Response fields

Example

POST /v1/api-keys/{key_id}/rotate

Parameters

Responses

Response fields

Example

GET /v1/me

Responses

Response fields

Example

approvals

GET /v1/approval-requests

Parameters

Responses

Response fields

Example

POST /v1/approval-requests

Request body application/json, required

Responses

Response fields

Example

GET /v1/approval-requests/{approval_id}

Parameters

Responses

Response fields

Example

POST /v1/approval-requests/{approval_id}/approve

Parameters

Request body application/json, required

Responses

Response fields

Example

POST /v1/approval-requests/{approval_id}/reject

GET `/v1/agents`

POST `/v1/agents`

GET `/v1/agents/{agent_id}`

PATCH `/v1/agents/{agent_id}`

GET `/v1/agents/{agent_id}/activity`

POST `/v1/agents/{agent_id}/keys`

GET `/v1/api-keys`

POST `/v1/api-keys`

DELETE `/v1/api-keys/{key_id}`

POST `/v1/api-keys/{key_id}/rotate`

GET `/v1/me`

GET `/v1/approval-requests`

POST `/v1/approval-requests`

GET `/v1/approval-requests/{approval_id}`

POST `/v1/approval-requests/{approval_id}/approve`

POST `/v1/approval-requests/{approval_id}/reject`

POST `/v1/approvals/{approval_id}/revoke`

POST `/v1/auth/invitations/{token}/accept`

POST `/v1/auth/logout`

POST `/v1/auth/magic-links`

GET `/v1/auth/magic-links/{token}`

GET `/v1/auth/me`

GET `/v1/auth/oauth/{provider}/callback`

GET `/v1/auth/oauth/{provider}/start`

GET `/v1/auth/passkeys`

POST `/v1/auth/passkeys/login/options`

POST `/v1/auth/passkeys/login/verify`

POST `/v1/auth/passkeys/register/options`

POST `/v1/auth/passkeys/register/verify`

DELETE `/v1/auth/passkeys/{passkey_id}`

GET `/v1/auth/providers`