# Export the organization's data

> The organizations.export operation: POST /api/v1/organizations/{id}/exports in the REST API and the organizations_export tool in the MCP server.

Requests an export of everything in the organization: one JSON file per kind of record (legal entities,
brands, customers, subscriptions, invoices, the ledger, registrations, filings and the rest, both modes), plus
the PDFs of its invoices and credit notes, in one ZIP archive. Secrets, hashes and tokens are left out.

It's built in the background (poll `organizations.exports.list` until `status` is `ready`) and can be
downloaded from the console for 7 days. One export is built at a time. Closed organizations can still export.

Needs `org:admin` (organization owners and admins). Security tier for agents: it holds all of the
organization's data.

## At a glance

- **REST:** `POST /api/v1/organizations/{id}/exports`
- **MCP tool:** `organizations_export`
- **Operation ID:** `organizations.export`
- **Scope:** Organization
- **Permission:** `org:admin`
- **Risk tier:** `security`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** API key with the `org:admin` scope
- **Since:** M12

## Request

### Path parameters

| Field | Type       | Description |
| ----- | ---------- | ----------- |
| `id`  | `org_…` ID |             |

### Body

This operation takes no body.

## Response

`201 Created` with a JSON object:

| Field              | Type                                                     | Description                                                                              |
| ------------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `id`               | `exp_…` ID                                               |                                                                                          |
| `object`           | `"organization_export"`                                  |                                                                                          |
| `status`           | one of `queued`, `running`, `ready`, `expired`, `failed` | `queued`, `running`, then `ready` (downloadable for 7 days, then `expired`) or `failed`. |
| `requestedBy`      | object                                                   |                                                                                          |
| `requestedBy.type` | string                                                   |                                                                                          |
| `requestedBy.id`   | string                                                   |                                                                                          |
| `file`             | object or null                                           |                                                                                          |
| `failure`          | object or null                                           |                                                                                          |
| `readyAt`          | date-time or null                                        |                                                                                          |
| `expiresAt`        | date-time or null                                        |                                                                                          |
| `createdAt`        | date-time                                                |                                                                                          |
| `updatedAt`        | date-time                                                |                                                                                          |

## Examples

### Request an export

```http
POST /api/v1/organizations/org_01m4tx5nj7ekd958x53w4bntcg/exports
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
```

Response (`201`):

```json
{
  "id": "exp_01m4tx5nj8emwbyf7y9vcf47xf",
  "object": "organization_export",
  "status": "queued",
  "requestedBy": {
    "type": "user",
    "id": "usr_01m4tx5nj8emwbyf7y9vcf47xa"
  },
  "file": null,
  "failure": null,
  "readyAt": null,
  "expiresAt": null,
  "createdAt": "2026-10-26T09:00:00.000Z",
  "updatedAt": "2026-10-26T09:00:00.000Z"
}
```

## Errors

| Code                                                                                                               | HTTP status | When                                          | What to do                                                                                           |
| ------------------------------------------------------------------------------------------------------------------ | ----------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`organization_export_in_progress`](https://ownrecord.io/docs/reference/errors.md#organization_export_in_progress) | 409         | An export is already queued or being built.   | Wait for it to be ready (`organizations.exports.list`), then download it.                            |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)                           | 404         | The ID isn't the organization of the request. | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)                             | 403         | You can't export this organization.           | Ask an organization owner or admin for a role or scope that allows this action.                      |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed), [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`invalid_json`](https://ownrecord.io/docs/reference/errors.md#invalid_json), [`unsupported_media_type`](https://ownrecord.io/docs/reference/errors.md#unsupported_media_type), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`idempotency_key_required`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_required), [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused), [`idempotency_in_progress`](https://ownrecord.io/docs/reference/errors.md#idempotency_in_progress), [`approval_required`](https://ownrecord.io/docs/reference/errors.md#approval_required), [`approval_rejected`](https://ownrecord.io/docs/reference/errors.md#approval_rejected), [`approval_expired`](https://ownrecord.io/docs/reference/errors.md#approval_expired), [`stale_approval`](https://ownrecord.io/docs/reference/errors.md#stale_approval), [`approval_policy_denied`](https://ownrecord.io/docs/reference/errors.md#approval_policy_denied), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).