API schemas, F to O
Updated
55 named objects of the Fax for Agents API, from FaxCreate to faxforagents__auth__schemas__Me, as the API sends and accepts them. From the OpenAPI document version 1.20.0, snapshot of 2026-11-13. All 173 schemas are listed by name.
FaxCreate
M9: an approved request authorizes the send; without one a quote that needs authorization is evaluated against the caller's delegated policies.
| 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
| 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 | |
delete_after_send | boolean | no | |
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 | |
one_time | object OneTimeJob or null | no | |
one_time_order_id | string or null | no | The one-time order this fax was paid by; null for a wallet fax. |
pages_sent | integer | yes | |
provider | string | yes | |
provider_ref | string or null | yes | |
quality | string | no | |
quote_id | string or null | yes | |
route | string | yes | |
sender_name | string or null | no | |
state | string (queued, active, partial, failed, unknown, delivered) | yes | |
to | string | yes | |
transmitted_sha256 | string or null | yes | |
updated_at | string | yes |
FaxJobPage
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object FaxJob | yes | |
next_cursor | string or null | no |
Grant
| Field | Type | Required | Description |
|---|---|---|---|
client_host | string | yes | |
client_id | string | yes | |
client_name | string or null | yes | |
created_at | string | yes | |
environment | string (test, live) | yes | |
id | string | yes | |
last_used_at | string or null | yes | |
org_id | string | yes | |
organization | string | yes | |
revoked_at | string or null | yes | |
scopes | array of string | yes | |
user_id | string | yes |
GrantList
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object Grant | yes | |
next_cursor | string or null | no |
InboxItemDetail
| Field | Type | Required | Description |
|---|---|---|---|
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
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object faxforagents__api__routes__inbox__InboxItem | yes | |
next_cursor | string or null | no |
InboxUpdate
| Field | Type | Required | Description |
|---|---|---|---|
status | string (received, read, archived) or null | no |
Inventory
| Field | Type | Required | Description |
|---|---|---|---|
country | string | yes | |
items | array of object InventoryNumber | yes | |
locality | string or null | yes | |
note | string | yes | |
number_type | string | yes | |
recurring_period | string | yes |
InventoryNumber
| Field | Type | Required | Description |
|---|---|---|---|
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
| Field | Type | Required | Description |
|---|---|---|---|
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
| Field | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
role | string (owner, admin, member, viewer) | no |
InvitationList
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object Invitation | yes |
Invoice
| Field | Type | Required | Description |
|---|---|---|---|
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
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object Invoice | yes | |
next_cursor | string or null | no |
LedgerEntry
| Field | Type | Required | Description |
|---|---|---|---|
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
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object LedgerEntry | yes | |
next_cursor | string or null | no |
MagicLinkRequest
| Field | Type | Required | Description |
|---|---|---|---|
email | string (email) | yes | |
next | string or null | no | An in-app path to open after sign-in. |
ref | string or null | no | A referral code from the link that brought the person, when the page has one. |
sub | string or null | no | The referral link's tag. |
Member
| Field | Type | Required | Description |
|---|---|---|---|
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
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object Member | yes |
MemberPatch
| 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
| Field | Type | Required | Description |
|---|---|---|---|
activated_at | string or null | yes | |
country | string | yes | |
created_at | string | yes | |
currency | string | yes | |
e164 | string | yes | |
email_pdf | boolean | no | When true, the notice mail of a fax received on this number carries the PDF as an attachment. Live numbers only. Off by default. |
environment | string (live, test) | yes | |
id | string | yes | |
inbound_status | string | yes | |
inbound_webhook_id | string or null | yes | |
label | string or null | yes | |
locality | string or null | yes | |
monthly_micro | integer | yes | |
number_type | string | yes | |
order_id | string or null | yes | |
project_id | string or null | yes | |
provider | string | yes | |
released_at | string or null | yes | |
renews_at | string or null | yes | |
status | string | yes |
NumberList
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object Number | yes |
NumberOrder
| 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
| 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. |
NumberOrderList
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object NumberOrder | yes |
NumberUpdate
| Field | Type | Required | Description |
|---|---|---|---|
email_pdf | boolean or null | no | Attach the PDF of each received fax to the notice mail. The mail goes to the verified address of an owner of the organization and to no other address. A PDF over 15 MB is not attached. It needs the scope number:buy. An agent, an OAuth connection and a connected app are refused. |
inbound_webhook_id | string or null | no | |
label | string or null | no | |
project_id | string or null | no |
OAuthConsent
| Field | Type | Required | Description |
|---|---|---|---|
client | object OAuthConsentClient | yes | |
default_environment | string (live, test) | yes | |
expires_at | string | yes | |
id | string | yes | |
organizations | array of object OAuthConsentOrganization | yes | |
redirect_host | string | yes | |
scopes_requested | array of string | yes |
OAuthConsentAutoSend
| Field | Type | Required | Description |
|---|---|---|---|
daily_max_jobs | integer | yes | |
enabled | boolean | yes | |
max_amount_micro | integer | yes |
OAuthConsentClient
| Field | Type | Required | Description |
|---|---|---|---|
first_seen | boolean | yes | This client was registered during this request. |
host | string | yes | The host the person is sending a credential to: the trust anchor. |
loopback | boolean | yes | The redirect goes to the person's own computer (an app they started). |
name | string or null | yes | The client's own name, shown as text beside the host. |
OAuthConsentDecision
| Field | Type | Required | Description |
|---|---|---|---|
auto_send | boolean or null | no | The consent screen's checkbox, owners only: false turns the organization's auto-send setting off for this environment, true turns it on with its current limits. Omitted leaves it. |
environment | string (live, test) | no | |
org_id | string | yes |
OAuthConsentOrganization
| Field | Type | Required | Description |
|---|---|---|---|
auto_send | object | no | The organization's auto-send setting per environment: whether connected apps send within the limits with no approval per fax (docs/APPROVALS.md, Auto-send setting). |
id | string | yes | |
name | string | yes | |
role | string | yes | |
scopes | array of string | yes | What the grant would carry for this organization and role. |
OAuthRedirect
| Field | Type | Required | Description |
|---|---|---|---|
redirect_to | string | yes | Where the browser goes next: the client's registered redirect URI. |
OneTimeCard
| Field | Type | Required | Description |
|---|---|---|---|
brand | string or null | yes | |
last4 | string or null | yes |
OneTimeCheckout
| Field | Type | Required | Description |
|---|---|---|---|
amount_micro | integer | yes | |
checkout_url | string | yes | |
currency | string | yes | |
expires_at | string | yes | |
order_id | string | yes |
OneTimeConfig
What the public send page and an agent read before an order: whether the product is open here, the card the order will be priced from (present only while open), the document limits and the policy the sender accepts. Prices are integer micro-USD; the dollar figure is the client's to format.
| Field | Type | Required | Description |
|---|---|---|---|
aup_url | string | yes | |
aup_version | string | yes | |
currency | string | yes | |
effective_from | string | yes | |
enabled | boolean | yes | |
formats | array of string | yes | |
max_document_pages | integer | yes | |
max_text_chars | integer | yes | |
max_upload_bytes | integer | yes | |
price_version | string | yes | |
queue | object OneTimeQueue or null | no | The wait a fax ordered now would face for a carrier line. Null when one-time sends are closed here or the carrier has no line limit. |
reason | string or null | no | |
routes | object | yes | |
terms_url | string | yes |
OneTimeConfirm
| Field | Type | Required | Description |
|---|---|---|---|
token | string | yes | The token of the link in the confirmation mail. |
OneTimeConfirmSummary
What the confirm page shows before the click. ``state`` is ``ok`` while the link can still be used, else ``link_used`` or ``link_expired``. Reading it consumes nothing.
| Field | Type | Required | Description |
|---|---|---|---|
amount_micro | integer | yes | |
confirm_deadline_at | string or null | yes | |
currency | string | yes | |
document_pages | integer | yes | |
email | string | yes | |
order_id | string | yes | |
sender_name | string | yes | |
state | string (ok, link_used, link_expired) | yes | |
status | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes | |
to | string | yes |
OneTimeConfirmed
``signed_in`` says whether this browser now holds a session for the payer; ``me`` is then the same object ``GET /v1/auth/me`` answers (the CSRF token included).
| Field | Type | Required | Description |
|---|---|---|---|
me | object or null | no | |
order | object OneTimeOrder | yes | One order of the one-time send. ``next`` is what the caller does now: ``checkout`` (open the payment), ``confirm`` (the payer clicks the link in the mail), ``wait`` (nothing to do; read again) or ``done``. Money is integer micro-USD. ``captured_micro`` is what the card was charged, written only once the payment provider confirmed it. ``fax`` is the fax job once the order was released, with the carrier's evidence once it has any. |
signed_in | boolean | yes |
OneTimeFromQuote
| Field | Type | Required | Description |
|---|---|---|---|
accept_aup | boolean | no | A session sends true: the signed-in person accepts the acceptable use policy and the terms. A key's value is not recorded: the person who pays accepts on the order's page. |
approval_id | string or null | no | An approved, unused approval request for this quote (POST /v1/approval-requests). A key needs it unless a delegated policy allows the send. A session needs none. |
delete_after_send | boolean or null | no | Delete the document and the transmitted copy the moment the fax ends in delivered, partial or failed. The order, the receipt and the carrier evidence stay; they hold no document content. A fax that ends unknown keeps the document until the carrier reports, or until the retention period ends. Left out, the quote's own delete_after_send applies. |
email | string or null | no | |
quote_id | string | yes | |
sender_name | string | yes | Printed on the cover sheet. 2 to 120 characters. |
source_ref | string or null | no |
OneTimeJob
The order behind a fax job that a one-time send made: what was authorized, what was charged.
| Field | Type | Required | Description |
|---|---|---|---|
amount_micro | integer or null | no | |
captured_micro | integer or null | no | |
card | object OneTimeCard or null | no | |
document_pages | integer or null | no | The pages of the order's document. The cover sheet is not counted. |
order_id | string | yes | |
refunded_micro | integer or null | no | What was refunded to the card after the charge, in micro-units. |
status | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) or null | no |
OneTimeOrder
One order of the one-time send. ``next`` is what the caller does now: ``checkout`` (open the payment), ``confirm`` (the payer clicks the link in the mail), ``wait`` (nothing to do; read again) or ``done``. Money is integer micro-USD. ``captured_micro`` is what the card was charged, written only once the payment provider confirmed it. ``fax`` is the fax job once the order was released, with the carrier's evidence once it has any.
| Field | Type | Required | Description |
|---|---|---|---|
amount_micro | integer | yes | |
aup_accepted | boolean | no | Whether a person accepted the acceptable use policy and the terms for this order. False for an order a key created until the payer accepts on the order's page; the checkout needs it. |
aup_version | string | yes | |
authorized_at | string or null | yes | |
capture_deadline_at | string or null | yes | |
captured_micro | integer | yes | |
card | object OneTimeCard or null | yes | |
checkout_expires_at | string or null | yes | |
checkout_url | string or null | yes | |
confirm_deadline_at | string or null | yes | |
confirm_mail_sent_at | string or null | yes | |
cover | object or null | yes | |
created_at | string | yes | |
delete_after_send | boolean | no | The sender asked for the document and the transmitted copy to be deleted the moment the fax ends in delivered, partial or failed. |
document_deleted | boolean | no | True once no copy of the document is held: it was deleted after the send, by the retention period or by its owner, or the order ended before it was released and the uploaded file was removed. The order, the fax and the carrier evidence stay; they hold no document content. |
document_expires_at | string or null | no | When the retention period deletes the stored document. Null before the release and once the document is deleted. |
document_id | string or null | yes | |
document_pages | integer | yes | |
document_sha256 | string | yes | |
email | string | yes | |
email_verified | boolean | yes | |
environment | string (live, test) | yes | |
failure_code | string or null | yes | |
fax | object or null | no | The fax job (the FaxJob shape) once the order was released; null before. |
fax_job_id | string or null | yes | |
id | string | yes | |
next | string (checkout, confirm, wait, done) | yes | |
price | object OneTimePrice | yes | |
queue | object OneTimeQueue or null | no | The wait for a carrier line while the order has not ended and its fax is not on a line yet. Null for an ended order, a fax that is sending, and a test order. |
quote_id | string or null | yes | |
refunded_micro | integer | no | What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero when nothing was refunded. captured_micro stays what was charged. |
released_at | string or null | yes | |
resend_allowed_at | string or null | no | When the confirmation mail may be asked for again; null when it may not. |
route | string | yes | |
sender_name | string | yes | |
settled_at | string or null | yes | |
source | string (web, api, mcp) | yes | |
status | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes | |
status_url | string or null | no | The order's page for the person who pays or confirms, with a fresh status token. Present on a read by a key or session of the order's organization while the order is not done. |
to | string | yes | |
updated_at | string | yes | |
warnings | array of object | no |
OneTimeOrderCreated
The create answer: the order plus the status token. The token reads this one order, opens its checkout and asks for the confirmation mail again, with no key and no session, for seven days. Send it as ``X-FFA-Order-Token`` (or ``?t=``). ``status_url`` is the order's page in the app with the token.
| Field | Type | Required | Description |
|---|---|---|---|
amount_micro | integer | yes | |
aup_accepted | boolean | no | Whether a person accepted the acceptable use policy and the terms for this order. False for an order a key created until the payer accepts on the order's page; the checkout needs it. |
aup_version | string | yes | |
authorized_at | string or null | yes | |
capture_deadline_at | string or null | yes | |
captured_micro | integer | yes | |
card | object OneTimeCard or null | yes | |
checkout_expires_at | string or null | yes | |
checkout_url | string or null | yes | |
confirm_deadline_at | string or null | yes | |
confirm_mail_sent_at | string or null | yes | |
cover | object or null | yes | |
created_at | string | yes | |
delete_after_send | boolean | no | The sender asked for the document and the transmitted copy to be deleted the moment the fax ends in delivered, partial or failed. |
document_deleted | boolean | no | True once no copy of the document is held: it was deleted after the send, by the retention period or by its owner, or the order ended before it was released and the uploaded file was removed. The order, the fax and the carrier evidence stay; they hold no document content. |
document_expires_at | string or null | no | When the retention period deletes the stored document. Null before the release and once the document is deleted. |
document_id | string or null | yes | |
document_pages | integer | yes | |
document_sha256 | string | yes | |
email | string | yes | |
email_verified | boolean | yes | |
environment | string (live, test) | yes | |
failure_code | string or null | yes | |
fax | object or null | no | The fax job (the FaxJob shape) once the order was released; null before. |
fax_job_id | string or null | yes | |
id | string | yes | |
next | string (checkout, confirm, wait, done) | yes | |
price | object OneTimePrice | yes | |
queue | object OneTimeQueue or null | no | The wait for a carrier line while the order has not ended and its fax is not on a line yet. Null for an ended order, a fax that is sending, and a test order. |
quote_id | string or null | yes | |
refunded_micro | integer | no | What was refunded to the card after the charge, in micro-units, as the ledger holds it. Zero when nothing was refunded. captured_micro stays what was charged. |
released_at | string or null | yes | |
resend_allowed_at | string or null | no | When the confirmation mail may be asked for again; null when it may not. |
route | string | yes | |
sender_name | string | yes | |
settled_at | string or null | yes | |
source | string (web, api, mcp) | yes | |
status | string (draft, checkout_open, authorized, awaiting_confirmation, released, capturing, canceling, captured, released_hold, expired, refused, settle_failed) | yes | |
status_token | string | yes | |
status_url | string | yes | |
to | string | yes | |
updated_at | string | yes | |
warnings | array of object | no |
OneTimeOrderPage
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object OneTimeOrder | yes | |
next_cursor | string or null | no |
OneTimePrice
| Field | Type | Required | Description |
|---|---|---|---|
cover_included | boolean | yes | |
currency | string | yes | |
extra_page_micro | integer | yes | |
flat_micro | integer | yes | |
included_pages | integer | yes | |
price_version | string | yes |
OneTimeQueue
The wait for a carrier line. ``queued`` is true when a fax sent now, or this order's waiting fax, is estimated to wait more than ten minutes for a line: the order is kept and sent in turn, never dropped. The minutes are an estimate from the number of faxes ahead and the carrier's line count.
| Field | Type | Required | Description |
|---|---|---|---|
estimated_wait_minutes | integer | yes | |
jobs_ahead | integer | yes | |
queued | boolean | yes |
OneTimeRoute
| Field | Type | Required | Description |
|---|---|---|---|
cover_included | boolean | yes | |
extra_page_micro | integer | yes | |
flat_micro | integer | yes | |
included_pages | integer | yes | |
label | string | yes |
Organization
| Field | Type | Required | Description |
|---|---|---|---|
created_at | string | yes | |
id | string | yes | |
members | integer | yes | |
name | string | yes | |
role | string (owner, admin, member, viewer) or null | yes |
OrganizationList
| Field | Type | Required | Description |
|---|---|---|---|
items | array of object OrganizationSummary | yes |
OrganizationPatch
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes |
OrganizationSummary
| Field | Type | Required | Description |
|---|---|---|---|
id | string | yes | |
name | string | yes | |
role | string (owner, admin, member, viewer) | yes |
faxforagents__api__routes__inbox__InboxItem
| Field | Type | Required | Description |
|---|---|---|---|
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 |
faxforagents__api__schemas__InboxItem
| Field | Type | Required | Description |
|---|---|---|---|
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 |
faxforagents__api__schemas__Me
| Field | Type | Required | Description |
|---|---|---|---|
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 |
faxforagents__auth__schemas__Me
| Field | Type | Required | Description |
|---|---|---|---|
csrf_token | string | yes | |
default_environment | string (live, test) | no | The environment the dashboard opens on: live once the organization has a funded wallet or a paid one-time order, else test. |
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 |