Upload a registration document

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`	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`	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`	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`	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`	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`	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`	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`	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`	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: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, idempotency_key_required, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Path parameters#

Body#

Response#

Examples#

Upload the OSS submission receipt#

Errors#