# Organizations API reference > The organization operations of the Fax for Agents API. List your organizations, read and rename the current one, and ask for a data export or for deletion. Page: https://faxforagents.com/docs/api/reference/organizations/ Last changed: 2026-11-13 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](https://faxforagents.com/docs/api/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](https://faxforagents.com/docs/api/reference/auth/). The people of an organization are in the [members group](https://faxforagents.com/docs/api/reference/members/). ## 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 | Notes | | --- | --- | --- | --- | --- | | `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 | Description | | --- | --- | --- | --- | | `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 | Description | | --- | --- | --- | --- | | `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 | Description | | --- | --- | --- | --- | | `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 | Description | | --- | --- | --- | --- | | `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_..."` ```