# Upload a registration document

> The registrations.documents.upload operation: POST /api/v1/registrations/{id}/documents in the REST API and the registrations_documents_upload tool in the MCP server.

Uploads a document to a registration: a submission receipt, a registration confirmation, a company register
extract for a prerequisite. Send the file base64-encoded in `content`: a PDF, PNG, JPEG or WebP file of at
most 3 MB, with its `filename`. The type is read from the file itself.

The document is stored privately (spec §7.10) and returned with its `file_…` ID. Use that ID as the
`reference` of a prerequisite's attachment (`registrations.update_prerequisite`) or of the proof when you
mark the application submitted or the registration registered. Uploading the same file to the same
registration again returns the same document.

Write tier: tax managers, owners and admins. Dry-run it to check a file without storing it.

## At a glance

- **REST:** `POST /api/v1/registrations/{id}/documents`
- **MCP tool:** `registrations_documents_upload`
- **Operation ID:** `registrations.documents.upload`
- **Scope:** Legal entity
- **Permission:** `registrations:write`
- **Risk tier:** `write`
- **Dry run:** Supported (send `Ownrecord-Dry-Run: true`)
- **Idempotency:** `Idempotency-Key` required
- **Modes:** Test and live
- **Authentication:** API key with the `registrations:write` scope
- **Since:** M7

## Request

### Path parameters

| Field | Type   | Description                                                                               |
| ----- | ------ | ----------------------------------------------------------------------------------------- |
| `id`  | string | The registration (`regn_…`) or its regime's ID, e.g. `EU_OSS_UNION` or `US_SALES_TAX:TX`. |

### Body

A JSON object (`Content-Type: application/json`):

| Field         | Type                                                              | Required | Description                                                                           |
| ------------- | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------- |
| `content`     | string                                                            | Yes      | The file's bytes, base64-encoded: a PDF, PNG, JPEG or WebP file of at most 3 MB.      |
| `filename`    | string                                                            | No       | The file's name, shown in the console and used for downloads, e.g. `oss-receipt.pdf`. |
| `contentType` | one of `application/pdf`, `image/png`, `image/jpeg`, `image/webp` | No       | The file's type. Optional: it is read from the file, and must agree when given.       |

## Response

`201 Created` with a JSON object:

| Field            | Type                                                              | Description |
| ---------------- | ----------------------------------------------------------------- | ----------- |
| `id`             | `file_…` ID                                                       |             |
| `object`         | `"registration_document"`                                         |             |
| `registrationId` | `regn_…` ID                                                       |             |
| `livemode`       | boolean                                                           |             |
| `filename`       | string or null                                                    |             |
| `contentType`    | one of `application/pdf`, `image/png`, `image/jpeg`, `image/webp` |             |
| `size`           | integer (at least 0)                                              |             |
| `sha256`         | string                                                            |             |
| `createdAt`      | date-time                                                         |             |

## Examples

### Upload the OSS submission receipt

```http
POST /api/v1/registrations/EU_OSS_NON_UNION/documents
Authorization: Bearer or_test_…
Idempotency-Key: 3f1c9a52-7d0e-4b8f-9a61-0c2d5e8b7f14
Content-Type: application/json

{
  "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==",
  "filename": "oss-submission-receipt.pdf"
}
```

Response (`201`):

```json
{
  "id": "file_01m4tx5nj8emwbyf7y9vcf47xq",
  "object": "registration_document",
  "registrationId": "regn_01m4tx5nj8emwbyf7y9vcf47xk",
  "livemode": true,
  "filename": "oss-submission-receipt.pdf",
  "contentType": "application/pdf",
  "size": 82,
  "sha256": "36dc4d8396e18eff67cf01ca1121f420465e698179be0d927351dbe6ac07884d",
  "createdAt": "2026-10-20T08:15:00.000Z"
}
```

## Errors

| Code                                                                                             | HTTP status | When                                                                                                                                            | What to do                                                                                                                                         |
| ------------------------------------------------------------------------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)           | 400         | The content isn't base64, is larger than 3 MB, isn't a PDF, PNG, JPEG or WebP file, or isn't the `contentType` given (`param` names the field). | Fix the fields listed in `details.issues` and send the request again.                                                                              |
| [`upstream_timeout`](https://ownrecord.io/docs/reference/errors.md#upstream_timeout)             | 502         | The file store didn't answer in time; nothing was recorded. Retry.                                                                              | Retry the request with the same Idempotency-Key after a short wait.                                                                                |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)         | 404         | This entity has no such registration in this mode.                                                                                              | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                                               |
| [`jurisdiction_blocked`](https://ownrecord.io/docs/reference/errors.md#jurisdiction_blocked)     | 422         | The tax knowledge no longer has a usable regime for this registration, so it can't change now.                                                  | This jurisdiction isn't covered by usable tax knowledge for this seller. Contact support if you need to sell there.                                |
| [`idempotency_key_reused`](https://ownrecord.io/docs/reference/errors.md#idempotency_key_reused) | 409         | The idempotency key was used before with another input.                                                                                         | Use a new Idempotency-Key for a different request, or resend the original request unchanged.                                                       |
| [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed)     | 403         | You have no live-mode access, so you can't change live registrations.                                                                           | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin.                        |
| [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required)                 | 400         | The request names no legal entity (an org key without `Ownrecord-Entity`).                                                                      | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)           | 403         | You can't change this entity's registrations (tax managers, owners and admins can).                                                             | Ask an organization owner or admin for a role or scope that allows this action.                                                                    |
| [`version_conflict`](https://ownrecord.io/docs/reference/errors.md#version_conflict)             | 409         | The registration changed at the same moment (a sale or the deadline job); reload and retry.                                                     | Fetch the object again and retry the change.                                                                                                       |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`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_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).