Legal identifiers (VAT ids, register numbers and similar) of your organization and of your customers, per country: which kinds apply, validation dry-runs, VIES checks and register facts.
List the identifier kinds a customer of a country may hold
Deprecated: use GET /identifier-kinds?holder=customer instead. Removed on 2026-11-30.
The identifier registry filtered for a buyer billed in the given country, labelled in that country's vocabulary — the picker of the customer create form, which has no customer id yet to ask GET /customers/{customerId}/identifiers.
Required scope: tax.profile.read (Read tax profile).
query Parameters
countryISO 3166-1 alpha-2 billing country of the customer; the kinds and their labels are that country's. Empty lists the kinds that are not bound to one country.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List the identifier kinds a customer of a country may hold › Responses
OK
Dry-run an identifier value for a customer not created yet
Deprecated: use POST /identifier-kinds/validate?holder=customer instead. Removed on 2026-11-30.
The customer dry run without a customer: the same pattern and check-digit gate the create path runs on each entry of identifiers. Writes nothing; a wrong value is a 200 with ok=false.
Required scope: tax.profile.read (Read tax profile).
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Dry-run an identifier value for a customer not created yet › Request Body
kindvaluecountryvalid_fromvalid_toDry-run an identifier value for a customer not created yet › Responses
OK
List a customer's legal identifiers
The buyer's typed identifiers, labelled by the register that issued them rather than by the seller's vocabulary. available_kinds is deprecated: read GET /identifier-kinds?holder=customer&country=<the customer's country>. From 2026-11-30 this list answers {data: [...], pagination}: the identifiers move from data.identifiers to data.
Required scope: tax.profile.read (Read tax profile).
path Parameters
customerIdHeaders
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List a customer's legal identifiers › Responses
OK
Add or update one of a customer's legal identifiers
Same pattern and check-digit gate as the organization's own. An unrecognised key is refused; it is never stored as a generic tax registration.
Required scope: tax.profile.write (Write tax profile).
path Parameters
customerIdHeaders
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Add or update one of a customer's legal identifiers › Request Body
kindvaluecountryvalid_fromvalid_toAdd or update one of a customer's legal identifiers › Responses
OK
Dry-run one of a customer's identifier values
The buyer analogue of the organization dry run, labelled by the register that issues the kind rather than by the seller's vocabulary. Writes nothing.
Required scope: tax.profile.read (Read tax profile).
path Parameters
customerIdHeaders
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Dry-run one of a customer's identifier values › Request Body
kindvaluecountryvalid_fromvalid_toDry-run one of a customer's identifier values › Responses
OK
Delete one of a customer's legal identifiers
Permanently removes an identifier entered by mistake and answers 204; the row is deleted rather than end-dated, and the removal is recorded in the customer's audit trail. Nothing cascades to documents already issued: the buyer VAT ID on them was frozen at issue. The identifier is looked up by its own id among the customer identifiers of your current workspace.
Required scope: tax.profile.write (Write tax profile).
path Parameters
customerIdidHeaders
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete one of a customer's legal identifiers › Responses
No Content
List the identifier kinds a party of a country may hold
The identifier registry filtered for one holder — a customer billed in country, or an organization established in it — labelled in that country's vocabulary, as one page. Each kind that fills a single-valued fact carries its slot. It is the picker of a form whose party does not exist yet; an existing party's identifiers are read under the party.
Required scope: tax.profile.read (Read tax profile).
query Parameters
holderWhose identifier: customer (a buyer billed in country) or organization (an organization established in country).
countryISO 3166-1 alpha-2 country; the kinds and their labels are that country's. Empty lists the kinds that are not bound to one country.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List the identifier kinds a party of a country may hold › Responses
OK
Dry-run an identifier value for a party not created yet
Runs the same pattern and check-digit gate the write path runs on an identifier of the holder, and writes nothing. The label is in the vocabulary of the body's country. A malformed question (an unknown kind, a kind the holder may not hold) is a 400; a wrong value is a 200 with ok=false.
Required scope: tax.profile.read (Read tax profile).
query Parameters
holderWhose identifier the value is: customer or organization.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Dry-run an identifier value for a party not created yet › Request Body
kindvaluecountryvalid_fromvalid_toDry-run an identifier value for a party not created yet › Responses
OK
List the identifier kinds an organization of a country may hold
Deprecated: use GET /identifier-kinds?holder=organization instead. Removed on 2026-11-30.
The identifier registry filtered for an organization established in the given country, labelled in that country's vocabulary, each slot-owned kind marked with its slot — the picker of a create form whose organization does not exist yet.
Required scope: tax.profile.read (Read tax profile).
query Parameters
countryISO 3166-1 alpha-2 country the organization is established in; the kinds and their labels are that country's. Empty lists the kinds that are not bound to one country.
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List the identifier kinds an organization of a country may hold › Responses
OK
Legal-identity readiness for the governing jurisdiction
For each surface the law reaches — invoice, credit note, quote, business e-mail, portal imprint — which identifiers and register facts the governing jurisdiction requires, which are on file, and which are required only under a condition that cannot be evaluated yet. Every item carries the statutory source it comes from.
Required scope: tax.profile.read (Read tax profile).
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Legal-identity readiness for the governing jurisdiction › Responses
OK
List the organization's legal identifiers
Returns the typed identifiers the organization holds (VAT id, national tax number, commercial-register number, SIREN, KVK, CHE-UID, org-nr, Peppol participant id …) together with the kinds its governing jurisdiction makes available and requires. available_kinds is deprecated: read GET /identifier-kinds?holder=organization&country=<the organization's country>. From 2026-11-30 this list answers {data: [...], pagination}: the identifiers move from data.identifiers to data.
Required scope: tax.profile.read (Read tax profile).
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
List the organization's legal identifiers › Responses
OK
Add or update one of the organization's legal identifiers
Writes one identifier. The value is normalized and gated on the kind's pattern and, where a dossier documents one, its check digit; an unknown kind is refused rather than stored as a generic tax number. Re-posting a value that differs only in punctuation updates how it prints and does not create a second row.
Required scope: tax.profile.write (Write tax profile).
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Add or update one of the organization's legal identifiers › Request Body
kindvaluecountryvalid_fromvalid_toAdd or update one of the organization's legal identifiers › Responses
OK
Dry-run one identifier value against its kind
Runs the SAME pattern and check-digit gate the write path runs, and writes nothing. Answers whether the value is shaped like the kind, whether a check digit could be run at all, and whether it passed — three states a single boolean cannot carry. An unknown kind is still a 400; a wrong VALUE is a 200 with ok=false, because that is an answer rather than an error.
Required scope: tax.profile.read (Read tax profile).
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Dry-run one identifier value against its kind › Request Body
kindvaluecountryvalid_fromvalid_toDry-run one identifier value against its kind › Responses
OK
Check the organization's own VAT id against VIES
Asks the EU VIES service about the organization's current VAT identification number, as its own requester, and records the answer on that identifier: verified_status VERIFIED or REFUSED with verified_at and, when VIES issued one, the consultation number in verification_ref. A VIES that does not answer (a member state down, a throttle, a timeout) is recorded as UNAVAILABLE and is not an error. Saving a VAT id on the company profile starts the same check in the background. A VAT id VIES does not hold (GB, CH, NO) is refused with 400.
Required scope: tax.profile.write (Write tax profile).
Headers
Idempotency-KeyUnique key that makes this POST safe to retry: repeats with the same key replay the first response instead of re-executing. Replays are scoped to the retrying principal (same API key / user) and kept for 24 hours. Required on every POST.
Client-generated idempotency key (e.g. a UUID).
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Check the organization's own VAT id against VIES › Responses
OK
Delete one of the organization's legal identifiers
Removes a mistyped identifier. A number that has LAPSED is not deleted: it is given an end date, so a document issued while it was live can still state it.
Required scope: tax.profile.write (Write tax profile).
path Parameters
idHeaders
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Delete one of the organization's legal identifiers › Responses
No Content
Get the organization's register facts
Legal form, seat region, registered office, share capital, liquidation status and the ordered list of representatives — the statements business-letter law requires beside the register number, none of which is an identifier. share_capital is the share capital as Money; share_capital_minor and share_capital_currency are deprecated.
Required scope: tax.profile.read (Read tax profile).
Headers
X-Workspace-IdSelects the workspace this request operates in, by workspace UUID or slug (e.g. a sandbox workspace for test integrations). Omitted: the organization's default live workspace. Unknown workspace: 404; workspace outside your organization: 403. Discover workspaces via GET /workspaces.
Workspace UUID or slug.
Get the organization's register facts › Responses
OK