Upload an authorization document

Uploads the signed document behind an authorization: a power of attorney, the appointment of a tax or fiscal representative. Send the file base64-encoded in content: a PDF, PNG, JPEG or WebP file of at most 3 MB, with its filename. It is stored privately (spec §7.10) and returned with its file_… ID: pass it as documentFileId to authorizations.create or authorizations.update. Never upload credentials (key files, certificates with their private key, password lists).

At a glance

REST: POST /api/v1/authorizations/documents
MCP tool: authorizations_documents_upload
Operation ID: authorizations.documents.upload
Scope: Legal entity
Permission: tasks: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 tasks:write scope
Since: M10

Request

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.
`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`	`"authorization_document"`
`entityId`	`ent_…` ID
`filename`	string or null
`contentType`	string
`size`	integer (at least 0)
`sha256`	string
`createdAt`	date-time

Examples

Upload a power of attorney

HTTP

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

{
  "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==",
  "filename": "power-of-attorney.pdf"
}

Response (201):

JSON

{
  "id": "file_01m4ttwd3veh9apbewxheq5xa2",
  "object": "authorization_document",
  "entityId": "ent_01m4ttwd3veh9apbewxheq5xh4",
  "filename": "power-of-attorney.pdf",
  "contentType": "application/pdf",
  "size": 52114,
  "sha256": "8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b3a2f1e0d9c8b7a6f5e4d3c2b1a0f9e8d7c",
  "createdAt": "2026-01-05T09:58:00.000Z"
}

Errors

Code	HTTP status	When	What to do
`validation_failed`	400	The content isn't a PDF, PNG, JPEG or WebP file of at most 3 MB.	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.
`scope_required`	400	The request names no legal 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 manage this entity's tasks and authorizations.	Ask an organization owner or admin for a role or scope that allows this action.

It can also return these common errors: api_version_unsupported, invalid_json, unsupported_media_type, authentication_required, api_key_invalid, resource_not_found, idempotency_key_required, idempotency_key_reused, idempotency_in_progress, approval_required, approval_rejected, approval_expired, stale_approval, approval_policy_denied, rate_limited, internal_error.

At a glance#

Request#

Body#

Response#

Examples#

Upload a power of attorney#

Errors#