Organizations API reference

Updated Nov 13, 2026

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

An organization archive is downloaded with a signed link that is valid for 72 hours.
Asking for an export or for deletion of an organization needs org:admin, the owner's scope.
A data request answers 202, which means it was accepted and is not finished yet.

Operations

GET /v1/organization/export-archives/{token} Download an organization archive with a signed link valid for 72 hours
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)

What is the current organization?

The one a credential acts in. An API key belongs to one organization, so for an API key the current one is fixed. A signed-in person can belong to several and looks at one at a time. GET /v1/organizations/current returns it with its id, its name, the caller's role and the number of members. GET /v1/organizations lists every organization the caller belongs to, and needs no scope.

Switching between them is a session action in the auth group. The people of an organization are in the members group.

How is an organization renamed?

PATCH /v1/organizations/current takes a name. It needs member:admin. The name matters outside the dashboard too: a fax sent without a sender_name on its quote uses the organization's name to identify the sender.

How do I export an organization's data?

POST /v1/organizations/current/export-requests asks for an export. The answer is 202 with a message. The archive is built afterwards, and the owner gets a signed link to it.

GET /v1/organization/export-archives/{token} is that link. It is valid for 72 hours, and it takes the signature in the address and no API key. After that time, ask for a new export.

How is an organization deleted?

POST /v1/organizations/current/deletion-requests asks for the organization and its data to be deleted. It also answers 202: the request is recorded, and the deletion follows. Once an organization is being deleted its keys stop working, and a call answers 410 organization_deleted.

Both requests are for the owner. They need org:admin, and an agent key is never issued that scope. An agent cannot export or delete the organization it works for.

Each operation in detail

GET `/v1/organization/export-archives/{token}`

Download an organization archive with a signed link valid for 72 hours

Credential: the signed URL as it was given.

Parameters

GET /v1/organization/export-archives/{token} parameters
Name	In	Type	Required
`token`	path	string	yes
`exp`	query	string or null	no
`sig`	query	string or null	no

Responses

GET /v1/organization/export-archives/{token} responses
Status	Meaning
`200`	Successful Response
`404`	not_found: no such resource for this credential. A resource of another organization answers the same.
`422`	A field failed validation: invalid_request, with one entry per field in error.details, or a code that names the rule.

Example

curl https://api.faxforagents.com/v1/organization/export-archives/TOKEN

GET `/v1/organizations`

The organizations you belong to

Credential: an API key or a signed-in session.

Responses

GET /v1/organizations responses
Status	Meaning
`200`	Successful Response
`401`	No credential, or one that was not accepted: invalid_token for an API key, unauthenticated where a signed-in session is needed. error.details.reason says why a key was refused.
`404`	not_found: no such resource for this credential. A resource of another organization answers the same.
`429`	rate_limited. Retry-After and the RateLimit-* headers say when to try again.

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

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

Responses

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

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

Credential: an API key or a signed-in session. Scope: member:admin.

Parameters

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

Request body application/json, required

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

Responses

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

Response fields

PATCH /v1/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_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"example"}'

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

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

Credential: an API key or a signed-in session. Scope: org:admin.

Parameters

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

Responses

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

Response fields

POST /v1/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)

Credential: an API key or a signed-in session. Scope: org:admin.

Parameters

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

Responses

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

Response fields

POST /v1/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_..."

Organizations API reference

Operations

What is the current organization?

How is an organization renamed?

How do I export an organization's data?

How is an organization deleted?

Each operation in detail

GET /v1/organization/export-archives/{token}

Parameters

Responses

Example

GET /v1/organizations

Responses

Response fields

Example

GET /v1/organizations/current

Responses

Response fields

Example

PATCH /v1/organizations/current

Parameters

Request body application/json, required

Responses

Response fields

Example

POST /v1/organizations/current/deletion-requests

Parameters

Responses

Response fields

Example

POST /v1/organizations/current/export-requests

Parameters

Responses

Response fields

Example

Measure this visit?

GET `/v1/organization/export-archives/{token}`

GET `/v1/organizations`

GET `/v1/organizations/current`

PATCH `/v1/organizations/current`

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

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