{
"openapi": "3.1.2",
"info": {
"title": "AccountCloud API",
"version": "1",
"description": "The public AccountCloud API. Authenticate with a Bearer API key from the portal."
},
"servers": [
{
"url": "https://api.accountcloud.io/v1",
"description": "AccountCloud"
}
],
"security": [
{
"apiKey": []
}
],
"paths": {
"/me": {
"get": {
"operationId": "v1.me",
"description": "The account, the environment and the scopes of the API key you call\nwith, and the account's balance. Free, and a good first call to check\nthat your key works.",
"summary": "Who am I",
"tags": [
"Account"
],
"responses": {
"200": {
"description": "`MeResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MeResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/address/forms": {
"get": {
"operationId": "v1.address.forms.index",
"description": "The address form of every supported country (34: the EU, the EEA,\nSwitzerland, the United Kingdom, Turkey and the United Arab Emirates),\nor of the ones in `countries`. Partly based on Google's libaddressinput\ndata (CC BY 4.0).",
"summary": "Address forms of all countries",
"tags": [
"Addresses"
],
"parameters": [
{
"name": "countries",
"in": "query",
"description": "Only these countries, comma-separated.",
"schema": {
"type": [
"string",
"null"
],
"pattern": "^[A-Za-z]{2}(,[A-Za-z]{2})*$",
"maxLength": 200
},
"example": "NL,BE,DE"
},
{
"name": "locale",
"in": "query",
"description": "The language of the field labels: `en` (default) or `nl`.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"en",
"nl",
null
]
}
}
],
"responses": {
"200": {
"description": "Array of `AddressFormResource`",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AddressFormResource"
}
}
},
"required": [
"data"
]
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/address/forms/{country}": {
"get": {
"operationId": "v1.address.forms.show",
"description": "The fields an address has in this country, in the order to ask them,\nwhich of them are required, what the postcode looks like and the\nsubdivisions. A country we do not support gives `404` with\n`country_not_supported`.",
"summary": "Address form of a country",
"tags": [
"Addresses"
],
"parameters": [
{
"name": "country",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "locale",
"in": "query",
"description": "The language of the field labels: `en` (default) or `nl`.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"en",
"nl",
null
]
}
}
],
"responses": {
"200": {
"description": "`AddressFormResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFormResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "This country is not supported (`country_not_supported`, with `supported_countries`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/address/validate": {
"post": {
"operationId": "v1.address.validate",
"description": "Checks an address against the form of its country and returns it\nnormalised, with what is wrong per field. An incomplete or incorrect\naddress is still a `200`, with `valid: false`.",
"summary": "Validate an address",
"tags": [
"Addresses"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ValidateAddressRequest"
}
}
}
},
"responses": {
"200": {
"description": "`AddressValidationResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressValidationResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "A malformed `Idempotency-Key` or `AccountCloud-Entity` header (`invalid_idempotency_key`, `invalid_entity_reference`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The `Idempotency-Key` was used for a different request, or that request is still running (`idempotency_key_reused`, `idempotency_key_in_use`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/address/format": {
"post": {
"operationId": "v1.address.format",
"description": "The lines of an address as its country prints them: the convention\nof the address's country, not the sender's. With a `from_country`\nthat differs, the country line is added.",
"summary": "Format an address",
"tags": [
"Addresses"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FormatAddressRequest"
}
}
}
},
"responses": {
"200": {
"description": "`AddressFormatResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddressFormatResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "A malformed `Idempotency-Key` or `AccountCloud-Entity` header (`invalid_idempotency_key`, `invalid_entity_reference`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The `Idempotency-Key` was used for a different request, or that request is still running (`idempotency_key_reused`, `idempotency_key_in_use`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/companies": {
"get": {
"operationId": "v1.companies.index",
"description": "Find companies in a trade register by name, trade name or number: NL in\nthe KvK Handelsregister (asked now), BE in our daily copy of the KBO\nOpen Data. One result per company, at most `limit`. Ask\n`GET /v1/companies/{country}/{number}` for the full profile.\n\nDutch company data comes from the KvK, whose terms do not allow passing\nit on to third parties. It is only available to accounts with access;\nother accounts get `403` with `register_restricted`.",
"summary": "Search companies",
"tags": [
"Companies"
],
"parameters": [
{
"name": "country",
"in": "query",
"required": true,
"description": "The country of the register: `NL` or `BE`.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2
},
"example": "NL"
},
{
"name": "q",
"in": "query",
"required": true,
"description": "A (part of a) name or trade name, or a registration number: 8 digits for NL, the (start of the) enterprise number for BE.",
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 100
},
"example": "bakkerij"
},
{
"name": "limit",
"in": "query",
"description": "At most 100; default 10.",
"schema": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CompanySearchHitResource"
}
},
"source": {
"type": "object",
"description": "Where the results come from.",
"properties": {
"register": {
"type": "string",
"description": "`kvk` or `kbo`.",
"enum": [
"kvk",
"kbo"
]
},
"name": {
"type": "string",
"enum": [
"KvK Handelsregister",
"KBO Open Data (Crossroads Bank for Enterprises)"
]
},
"freshness": {
"type": "string",
"description": "`live`: the register was asked now. `cached`: our copy.",
"enum": [
"cached",
"live"
]
},
"retrieved_at": {
"type": [
"string",
"null"
],
"description": "When the register gave us these results; for BE the date of the KBO export."
},
"notice": {
"description": "The attribution the register requires with its data, verbatim.",
"anyOf": [
{
"type": "string"
},
{
"type": "null"
},
{
"type": "string",
"enum": [
"Voor actuele informatie met juridische derdenwerking dient u altijd het Handelsregister te raadplegen."
]
}
]
}
},
"required": [
"register",
"name",
"freshness",
"retrieved_at",
"notice"
]
}
},
"required": [
"object",
"data",
"source"
]
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`). For company data also an account that may not receive the data of this register (`register_restricted`, with `country`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "This country is not supported (`country_not_supported`, with `supported_countries`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/companies/{country}/{number}": {
"get": {
"operationId": "v1.companies.show",
"description": "The profile of a company by its registration number: the KvK number\nfor `NL` (8 digits), the enterprise number for `BE` (10 digits, dots\nallowed). `source` says where it comes from and how old it is.\n\nFor NL the price depends on where the data comes from: our copy\n(`source.freshness: cached`) costs less than asking the KvK now\n(`live`). With `freshness=auto` you pay for what you got. A number the\nKvK does not know costs what the KvK charges us for asking; any other\n\"not found\" is free. BE always comes from our daily copy of the KBO.\n\nDutch company data comes from the KvK, whose terms do not allow passing\nit on to third parties. It is only available to accounts with access;\nother accounts get `403` with `register_restricted`.",
"summary": "Get a company",
"tags": [
"Companies"
],
"parameters": [
{
"name": "country",
"in": "path",
"required": true,
"description": "The country of the register: `NL` or `BE`.",
"schema": {
"type": "string"
}
},
{
"name": "number",
"in": "path",
"required": true,
"description": "The KvK number (NL) or the enterprise number (BE).",
"schema": {
"type": "string"
}
},
{
"name": "freshness",
"in": "query",
"description": "Where the profile may come from. `auto` (default): our copy when it is younger than `max_age_days`, otherwise the register now. `cached`: only our copy, whatever its age. `live`: always the register now (NL only; BE comes from our daily copy of the KBO).\n| |\n|---|\n| `auto`
Our copy when it is younger than `max_age_days`, otherwise the register. |\n| `cached`
Only our copy, whatever its age. |\n| `live`
Always the register, now. |",
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/CompanyFreshness"
},
{
"type": "null"
}
]
}
},
{
"name": "max_age_days",
"in": "query",
"description": "With `freshness=auto`: how old our copy may be, in days. `0` always asks the register. Defaults to our own refresh period. Ignored for BE.",
"schema": {
"type": [
"integer",
"null"
],
"minimum": 0,
"maximum": 3650
},
"example": 7
}
],
"responses": {
"200": {
"description": "`CompanyResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CompanyResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`). For company data also an account that may not receive the data of this register (`register_restricted`, with `country`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "The country has no register here (`country_not_supported`, with `supported_countries`), the register has no company with this number (`company_not_found`), or with `freshness=cached` we hold no copy of it yet (`company_not_cached`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/documents": {
"post": {
"operationId": "v1.documents.store",
"description": "Send an invoice or receipt (PDF, JPEG or PNG, at most 10 MB) as JSON with\nbase64, or as multipart. It is read asynchronously: the answer is `202`\nwith the new document, and `GET /v1/documents/{id}` or the webhooks tell\nwhen it is done. `processing: automatic` is read by OCR; `processing:\nverified` is then checked by a processor within 24 working hours.\n\nThe same file within the same account, environment, entity and\n`processing` answers `200` with the earlier document (`duplicate_of`\nset), and costs nothing. Use an `Idempotency-Key` to retry safely.",
"summary": "Send a document",
"tags": [
"Documents"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/StoreDocumentRequest"
}
}
}
},
"responses": {
"202": {
"description": "`DocumentResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"200": {
"description": "`DocumentResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "A malformed `Idempotency-Key` or `AccountCloud-Entity` header (`invalid_idempotency_key`, `invalid_entity_reference`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`). For `processing: verified` also `verified_not_enabled`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The `Idempotency-Key` was used for a different request, or that request is still running (`idempotency_key_reused`, `idempotency_key_in_use`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "The file is larger than 10 MB (`file_too_large`, with `max_bytes`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"415": {
"description": "The file is not a PDF, JPEG or PNG; the type is decided from the content, not the file name (`unsupported_media_type`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`, see `errors`), no file was sent (`file_missing`), the base64 is broken (`invalid_base64`), the PDF is encrypted or has too many pages (`encrypted_pdf`, `too_many_pages`), or an option has a value that is not allowed (`invalid_option`, with `field`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds. For `processing: verified` also `verified_daily_limit`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
},
"get": {
"operationId": "v1.documents.index",
"description": "Newest first, without their results. Paged with a cursor: pass\n`next_cursor` as `cursor` for the next page. With an\n`AccountCloud-Entity` header, only that entity's documents.",
"summary": "List documents",
"tags": [
"Documents"
],
"parameters": [
{
"name": "status",
"in": "query",
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/DocumentStatus"
},
{
"type": "null"
}
]
}
},
{
"name": "processing",
"in": "query",
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/DocumentProcessing"
},
{
"type": "null"
}
]
}
},
{
"name": "reference",
"in": "query",
"description": "Only documents with this `reference`.",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 255
}
},
{
"name": "created_after",
"in": "query",
"description": "ISO 8601.",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "created_before",
"in": "query",
"description": "ISO 8601.",
"schema": {
"type": [
"string",
"null"
],
"format": "date-time"
}
},
{
"name": "limit",
"in": "query",
"description": "At most 100; default 25.",
"schema": {
"type": [
"integer",
"null"
],
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"description": "The `next_cursor` of the previous page.",
"schema": {
"type": [
"string",
"null"
],
"maxLength": 500
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "list"
},
"data": {
"type": "array",
"items": {
"$ref": "#/components/schemas/DocumentListItemResource"
}
},
"has_more": {
"type": "boolean"
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Pass as `cursor` for the next page; null on the last page."
}
},
"required": [
"object",
"data",
"has_more",
"next_cursor"
]
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/documents/{document}": {
"get": {
"operationId": "v1.documents.show",
"description": "The status, the result, the warnings, the review, the UBL status and the\ncharge. With `include=boxes` also where each value stands on the page.\nAfter the retention period the document is still there, with\n`content_available: false` and `result: null`. With an\n`AccountCloud-Entity` header, only a document of that entity.",
"summary": "Get a document",
"tags": [
"Documents"
],
"parameters": [
{
"name": "document",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`DocumentResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "The document does not exist, belongs to another account, environment or entity (`AccountCloud-Entity`), or was deleted (`document_not_found`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
},
"delete": {
"operationId": "v1.documents.destroy",
"description": "Deletes the original, the result and the UBL at once; afterwards `GET`\nanswers `404`. The metadata (hash, pages, cost, times, outcome) stays 13\nmonths. A verified document that is not done yet is taken off the queue:\nit costs the OCR price when it was read already, otherwise nothing.",
"summary": "Delete a document",
"tags": [
"Documents"
],
"parameters": [
{
"name": "document",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "document"
},
"deleted": {
"type": "boolean"
}
},
"required": [
"id",
"object",
"deleted"
]
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "The document does not exist, belongs to another account, environment or entity (`AccountCloud-Entity`), or was deleted (`document_not_found`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/documents/{document}/feedback": {
"post": {
"operationId": "v1.documents.feedback",
"description": "Tell us which fields the OCR got wrong. With `allow_training: true` the\ndocument joins the set we test and improve the OCR with (`training:\naccepted`); with `false` only the report is kept. Reports on test\ndocuments are never shared. Free.",
"summary": "Report a wrong result",
"tags": [
"Documents"
],
"parameters": [
{
"name": "document",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SubmitFeedbackRequest"
}
}
}
},
"responses": {
"202": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"examples": [
"fbk_01jbx6y4q9t2m8rz1v3k5n7p0b"
]
},
"object": {
"type": "string",
"const": "feedback"
},
"document_id": {
"type": "string"
},
"training": {
"type": "string",
"description": "`accepted`: the document joins the training set. `stats_only`: only the report is kept.",
"enum": [
"accepted",
"stats_only"
]
}
},
"required": [
"id",
"object",
"document_id",
"training"
]
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "A malformed `Idempotency-Key` or `AccountCloud-Entity` header (`invalid_idempotency_key`, `invalid_entity_reference`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "The document does not exist, belongs to another account, environment or entity (`AccountCloud-Entity`), or was deleted (`document_not_found`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The `Idempotency-Key` was used for a different request, or that request is still running (`idempotency_key_reused`, `idempotency_key_in_use`). Or the original is deleted and no file was sent with the report (`feedback_window_closed`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`, see `errors`), a `field` is not a field of the result (`unknown_field`), or the file is not the original (`file_hash_mismatch`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds. Or the account sent the maximum number of reports for today in this environment (`feedback_limit_reached`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/pricing": {
"get": {
"operationId": "v1.pricing",
"description": "The base subscription and the price of every operation, in euros\nexcluding VAT. Needs no API key. Prices change with a date from which\nthey apply; this list shows what applies now. Names and descriptions\nare in English, or in Dutch with `locale=nl`.",
"summary": "Prices",
"tags": [
"Pricing"
],
"parameters": [
{
"name": "locale",
"in": "query",
"description": "The language of the names and descriptions: `en` (default) or `nl`.",
"schema": {
"type": [
"string",
"null"
],
"enum": [
"en",
"nl",
null
]
}
}
],
"responses": {
"200": {
"description": "`PricingResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PricingResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "A query parameter is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
}
},
"security": []
}
},
"/status": {
"get": {
"operationId": "v1.status",
"description": "Needs no API key. Use it to check that the API is reachable. `services`\nholds the status of the services that measure themselves: `ocr` (failed\ncalls and the waiting time of documents), `ubl` (the turnaround of\nverified documents), `company_nl` and `vat` (failed calls to the KvK and\nto VIES) and `company_be` (the age of our copy of the KBO). A service\nthat is not live yet is left out. Each status is `operational`,\n`degraded`, `partial_outage` or `major_outage`.",
"summary": "Platform status",
"tags": [
"Status"
],
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "string",
"const": "operational"
},
"checked_at": {
"type": "string",
"examples": [
"2026-11-03T14:20:41Z"
]
},
"services": {
"type": "object",
"additionalProperties": {
"type": "object",
"additionalProperties": {
"type": [
"number",
"string",
"null"
]
}
}
}
},
"required": [
"status",
"checked_at",
"services"
]
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
}
}
}
},
"security": []
}
},
"/documents/{document}/ubl": {
"get": {
"operationId": "v1.documents.ubl",
"description": "UBL 2.1 according to Peppol BIS Billing 3.0, as `application/xml`. Made\nfrom the result when it was not asked for at intake. The outcome of the\nvalidation is on the document, under `ubl`.",
"summary": "Download the UBL of a document",
"tags": [
"UBL"
],
"parameters": [
{
"name": "document",
"in": "path",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "",
"content": {
"application/xml; charset=UTF-8": {
"schema": {
"type": [
"string",
"null"
]
}
}
},
"headers": {
"Content-Disposition": {
"schema": {
"type": "string"
}
},
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "The document does not exist, belongs to another account, environment or entity (`AccountCloud-Entity`), or was deleted (`document_not_found`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The document is not completed yet, or no UBL could be made from it (`document_not_ready`; see `ubl.errors` on the document), or it was rejected (`document_rejected`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"410": {
"description": "The content of the document was deleted at the end of its retention period (`content_purged`). The metadata is still there.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/ubl/validate": {
"post": {
"operationId": "v1.ubl.validate",
"description": "Checks a UBL 2.1 Invoice or CreditNote against the UBL schema, EN 16931\nand Peppol BIS Billing 3.0. An invalid file is still a `200`, with\n`valid: false` and the broken rules. `complete` says whether the full\nofficial rule set ran.",
"summary": "Validate a UBL file",
"tags": [
"UBL"
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/ValidateUblRequest"
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"profile": {
"type": "string",
"const": "peppol-bis-billing-3.0"
},
"complete": {
"type": "boolean"
},
"engine": {
"type": "string",
"const": "php-subset"
},
"engine_error": {
"type": "string"
},
"artifacts": {
"type": "object",
"properties": {
"ubl": {
"type": "string",
"const": "2.1"
},
"peppol_bis": {
"type": "string",
"const": "3.0.20"
},
"cen_schematron": {
"type": "string",
"const": "1.3.15"
}
},
"required": [
"ubl",
"peppol_bis",
"cen_schematron"
]
},
"errors": {
"type": "array",
"items": {}
}
},
"required": [
"valid",
"profile",
"complete",
"engine",
"engine_error",
"artifacts",
"errors"
]
},
{
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"profile": {
"type": "string",
"const": "peppol-bis-billing-3.0"
},
"complete": {
"type": "boolean"
},
"engine": {
"type": "string",
"const": "saxon"
},
"engine_error": {
"type": "null"
},
"artifacts": {
"type": "object",
"properties": {
"ubl": {
"type": "string",
"const": "2.1"
},
"peppol_bis": {
"type": "string",
"const": "3.0.20"
},
"cen_schematron": {
"type": "string",
"const": "1.3.15"
}
},
"required": [
"ubl",
"peppol_bis",
"cen_schematron"
]
},
"errors": {
"type": "array",
"items": {}
}
},
"required": [
"valid",
"profile",
"complete",
"engine",
"engine_error",
"artifacts",
"errors"
]
},
{
"type": "object",
"properties": {
"valid": {
"type": "boolean"
},
"profile": {
"type": "string",
"const": "peppol-bis-billing-3.0"
},
"complete": {
"type": "boolean"
},
"engine": {
"type": "string",
"const": "php-subset"
},
"engine_error": {
"type": "null"
},
"artifacts": {
"type": "object",
"properties": {
"ubl": {
"type": "string",
"const": "2.1"
},
"peppol_bis": {
"type": "string",
"const": "3.0.20"
},
"cen_schematron": {
"type": "string",
"const": "1.3.15"
}
},
"required": [
"ubl",
"peppol_bis",
"cen_schematron"
]
},
"errors": {
"type": "array",
"items": {}
}
},
"required": [
"valid",
"profile",
"complete",
"engine",
"engine_error",
"artifacts",
"errors"
]
}
]
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"400": {
"description": "A malformed `Idempotency-Key` or `AccountCloud-Entity` header (`invalid_idempotency_key`, `invalid_entity_reference`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"409": {
"description": "The `Idempotency-Key` was used for a different request, or that request is still running (`idempotency_key_reused`, `idempotency_key_in_use`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"413": {
"description": "The file is larger than 10 MB (`file_too_large`, with `max_bytes`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"422": {
"description": "The request is not valid (`validation_failed`); see `errors`.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
},
"/vat-numbers/{vat_number}": {
"get": {
"operationId": "v1.vat-numbers.show",
"description": "Checks an EU VAT number at VIES, the system of the European Commission,\nat this moment. Send the number with its country code (`NL123456789B01`;\nspaces, dots and dashes are allowed). When VIES confirms it, the answer\nhas the name and address the member state shares, and a\n`consultation_number` that proves the check: keep it with the invoice,\nfor example for a reverse-charge supply.\n\nA number in the wrong format is `valid: false` without asking VIES, and\ncosts nothing. When VIES or the register of the member state does not\nanswer, the answer is `503` with `provider_unavailable`, also free.",
"summary": "Validate a VAT number",
"tags": [
"VAT numbers"
],
"parameters": [
{
"name": "vat_number",
"in": "path",
"required": true,
"description": "The VAT number with its country code, for example `NL123456789B01`.",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "`VatNumberResource`",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VatNumberResource"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request. Quote it when you contact support.",
"schema": {
"type": "string"
}
},
"AccountCloud-Charged": {
"description": "What this call cost, in euros (`0.0000` for a free call or a test key). Example: `0.0350`.",
"schema": {
"type": "string"
}
},
"AccountCloud-Balance": {
"description": "With a live key, after a charged call: the credit you have left, in euros.",
"schema": {
"type": "string"
}
},
"RateLimit-Policy": {
"description": "The limits for this key: requests per minute and per UTC day. Example: `\"minute\";q=600;w=60, \"day\";q=250000;w=86400`.",
"schema": {
"type": "string"
}
},
"RateLimit": {
"description": "What is left in each window (`r`) and the seconds until it resets (`t`). Example: `\"minute\";r=599;t=60, \"day\";r=249999;t=43200`.",
"schema": {
"type": "string"
}
}
}
},
"401": {
"description": "The API key is missing, unknown, revoked or expired (`unauthenticated`, `invalid_api_key`, `api_key_expired`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"402": {
"description": "The credit does not cover this call (`insufficient_credits`). Top up in the portal. Test keys are never charged.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"403": {
"description": "The key may not do this: wrong IP address, missing scope, an account that is not active, or a live key of an account whose subscription has ended (`ip_not_allowed`, `insufficient_scope`, `account_inactive`, `account_disabled`, `subscription_ended`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"404": {
"description": "The VAT number is not of an EU member state (`country_not_supported`, with `supported_countries`).",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
}
}
},
"429": {
"description": "Too many requests (`rate_limit_exceeded`), the daily quota is used up (`daily_quota_exceeded`), or the key reached its monthly spending cap (`monthly_cap_reached`). Wait for `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
},
"503": {
"description": "Temporarily unavailable (`api_unavailable`, `product_unavailable`, `operation_unavailable`, `provider_unavailable`). Nothing is charged. Retry after `Retry-After` seconds.",
"content": {
"application/problem+json": {
"schema": {
"$ref": "#/components/schemas/Problem"
}
}
},
"headers": {
"X-Request-Id": {
"description": "The id of this request.",
"schema": {
"type": "string"
}
},
"Retry-After": {
"description": "Seconds to wait before retrying.",
"schema": {
"type": "integer"
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"apiKey": {
"type": "http",
"description": "Your API key from the portal: `ac_live_\u2026` for live, `ac_test_\u2026` for test. Send it as `Authorization: Bearer `.",
"scheme": "bearer"
}
},
"schemas": {
"AddressFormResource": {
"type": "object",
"properties": {
"country": {
"type": "string",
"examples": [
"NL"
]
},
"verified": {
"type": "boolean",
"description": "Whether the form was checked against the rules of the country's postal operator."
},
"fields": {
"type": "array",
"description": "The fields, in the order to ask them. `id` is the key of the field in the `address` of the other address operations. `type` is `text`, or `select` for a closed list: the `options`, or the country's `subdivisions` (`options_source`). `autocomplete` is the HTML autocomplete token. `layout` places the field on a 12-column grid: the `row`, its `column` in that row, and the columns it `span`s.",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"type": "string"
},
"type": {
"type": "string"
},
"required": {
"type": "boolean"
},
"max_length": {
"type": "integer"
},
"options": {
"type": [
"array",
"null"
],
"items": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"label": {
"type": "string"
}
},
"required": [
"value",
"label"
]
}
},
"options_source": {
"type": [
"string",
"null"
]
},
"example": {
"type": [
"string",
"null"
]
},
"autocomplete": {
"type": [
"string",
"null"
]
},
"layout": {
"type": "object",
"properties": {
"row": {
"type": "integer"
},
"column": {
"type": "integer"
},
"span": {
"type": "integer"
}
},
"required": [
"row",
"column",
"span"
]
}
},
"required": [
"id",
"label",
"type",
"required",
"max_length",
"options",
"options_source",
"example",
"autocomplete",
"layout"
]
}
},
"postcode": {
"type": "object",
"description": "`pattern` is a regular expression the postcode matches after normalising (upper case, the national spacing); `null` where the country has no postcodes.",
"properties": {
"pattern": {
"type": [
"string",
"null"
]
},
"example": {
"type": [
"string",
"null"
]
}
},
"required": [
"pattern",
"example"
]
},
"subdivisions": {
"type": "array",
"description": "The provinces, states or regions, where the country uses them. Send the `code`.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"name": {
"type": "string"
}
},
"required": [
"code",
"name"
]
}
}
},
"required": [
"country",
"verified",
"fields",
"postcode",
"subdivisions"
],
"title": "AddressFormResource"
},
"AddressFormatResource": {
"type": "object",
"properties": {
"country": {
"type": "string",
"examples": [
"NL"
]
},
"lines": {
"type": "string",
"description": "The lines of the address, as the country prints them, without the name of the recipient.",
"examples": [
[
"Hoofdstraat 12",
"1234 AB Amsterdam"
]
]
},
"text": {
"type": "string",
"description": "The lines joined with line breaks."
}
},
"required": [
"country",
"lines",
"text"
],
"title": "AddressFormatResource"
},
"AddressValidationResource": {
"type": "object",
"properties": {
"valid": {
"type": "string",
"description": "Whether the address is complete and correct for its country."
},
"address": {
"type": "object",
"description": "The address normalised: trimmed, empty fields left out, the postcode in its national form and a subdivision as its code. Store this one.",
"examples": [
{
"country": "NL",
"street": "Hoofdstraat",
"house_number": "12",
"postal_code": "1234 AB",
"city": "Amsterdam"
}
],
"additionalProperties": {
"type": "string"
}
},
"errors": {
"type": "array",
"description": "What is wrong, per field. `code` is one of `required`, `too_long`, `postcode_invalid`, `subdivision_invalid`, `invalid_option` and `unknown_field`.",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string"
},
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"field",
"code",
"message"
]
}
}
},
"required": [
"valid",
"address",
"errors"
],
"title": "AddressValidationResource"
},
"CompanyFreshness": {
"type": "string",
"description": "Where a company profile may come from (001 \u00a79.3).\n| |\n|---|\n| `auto`
Our copy when it is younger than `max_age_days`, otherwise the register. |\n| `cached`
Only our copy, whatever its age. |\n| `live`
Always the register, now. |",
"enum": [
"auto",
"cached",
"live"
],
"title": "CompanyFreshness"
},
"CompanyResource": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "company"
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2.",
"enum": [
"NL",
"BE"
],
"examples": [
"NL"
]
},
"number": {
"type": "string",
"description": "The registration number, digits only: the KvK number (NL) or the enterprise number (BE).",
"examples": [
"68750110"
]
},
"name": {
"type": "string",
"examples": [
"Test BV Donald"
]
},
"legal_form": {
"type": [
"string",
"null"
],
"description": "The legal form as the register writes it, in Dutch.",
"examples": [
"Besloten vennootschap"
]
},
"legal_form_code": {
"type": [
"string",
"null"
],
"description": "BE: the code of the legal form in the KBO (`014` is a public limited company). Null for NL."
},
"trade_names": {
"type": "array",
"description": "The other names the company trades under, the name itself included. BE: every name in the KBO, in every language.",
"items": {
"type": "string"
}
},
"vat_number": {
"type": [
"string",
"null"
],
"description": "BE: `BE` + the enterprise number. Null for NL: the KvK does not hold the VAT number. Check it with `GET /v1/vat-numbers/{vat_number}` before you rely on it.",
"examples": [
"BE0123456749"
]
},
"rsin": {
"type": [
"string",
"null"
],
"description": "NL: the RSIN of the legal entity, when the KvK gives it."
},
"establishment_number": {
"type": [
"string",
"null"
],
"description": "NL: the number of the main establishment (vestigingsnummer)."
},
"address": {
"type": [
"object",
"null"
],
"description": "The visiting address (NL) or the registered office (BE). `postal_code` is as the register writes it.",
"properties": {
"street": {
"type": [
"string",
"null"
]
},
"house_number": {
"type": [
"string",
"null"
]
},
"house_number_suffix": {
"type": [
"string",
"null"
]
},
"postal_code": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
}
},
"required": [
"street",
"house_number",
"house_number_suffix",
"postal_code",
"city",
"country"
]
},
"postal_address": {
"type": [
"object",
"null"
],
"description": "NL: the correspondence address, when it differs. A PO box has `street` `Postbus`.",
"properties": {
"street": {
"type": [
"string",
"null"
]
},
"house_number": {
"type": [
"string",
"null"
]
},
"house_number_suffix": {
"type": [
"string",
"null"
]
},
"postal_code": {
"type": [
"string",
"null"
]
},
"city": {
"type": [
"string",
"null"
]
},
"country": {
"type": [
"string",
"null"
]
}
},
"required": [
"street",
"house_number",
"house_number_suffix",
"postal_code",
"city",
"country"
]
},
"registration_date": {
"type": [
"string",
"null"
],
"description": "When the company was registered (NL) or started (BE). ISO 8601 date.",
"examples": [
"2017-05-19"
]
},
"end_date": {
"type": [
"string",
"null"
],
"description": "NL: when the registration ended, if it did. Ended BE companies are not in the KBO data."
},
"website": {
"type": [
"string",
"null"
]
},
"activities": {
"type": "array",
"description": "NL: the SBI activities, the main one with `main: true`. Empty for BE.",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"main": {
"type": "boolean"
}
},
"required": [
"code",
"description",
"main"
]
}
},
"source": {
"type": "object",
"description": "Where the data comes from and how old it is. Show `notice` and `retrieved_at` wherever you show the data.",
"properties": {
"register": {
"type": "string",
"description": "`kvk` or `kbo`.",
"enum": [
"kvk",
"kbo"
]
},
"name": {
"type": "string",
"enum": [
"KvK Handelsregister",
"KBO Open Data (Crossroads Bank for Enterprises)"
],
"examples": [
"KvK Handelsregister"
]
},
"freshness": {
"type": "string",
"description": "`cached`: from our copy. `live`: from the register, just now.",
"enum": [
"auto",
"cached",
"live"
]
},
"retrieved_at": {
"type": "string",
"description": "When the register gave us this data. For BE: the date of the KBO export it is current with.",
"examples": [
"2026-11-03T09:12:41Z"
]
},
"data_age_days": {
"type": "integer",
"description": "Whole days since `retrieved_at`."
},
"notice": {
"description": "The attribution the register requires with its data, verbatim.",
"examples": [
"Voor actuele informatie met juridische derdenwerking dient u altijd het Handelsregister te raadplegen."
],
"anyOf": [
{
"type": "string"
},
{
"type": "string",
"enum": [
"Voor actuele informatie met juridische derdenwerking dient u altijd het Handelsregister te raadplegen."
]
}
]
}
},
"required": [
"register",
"name",
"freshness",
"retrieved_at",
"data_age_days",
"notice"
]
}
},
"required": [
"object",
"country",
"number",
"name",
"legal_form",
"legal_form_code",
"trade_names",
"vat_number",
"rsin",
"establishment_number",
"address",
"postal_address",
"registration_date",
"end_date",
"website",
"activities",
"source"
],
"title": "CompanyResource"
},
"CompanySearchHitResource": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "company_summary"
},
"country": {
"type": "string",
"enum": [
"NL",
"BE"
],
"examples": [
"NL"
]
},
"number": {
"type": "string",
"examples": [
"68750110"
]
},
"name": {
"type": "string",
"examples": [
"Test BV Donald"
]
},
"city": {
"type": [
"string",
"null"
],
"description": "The place of the main establishment (NL) or the registered office (BE), when known."
},
"href": {
"type": "string",
"description": "The profile of this company.",
"examples": [
"/v1/companies/NL/68750110"
]
}
},
"required": [
"object",
"country",
"number",
"name",
"city",
"href"
],
"title": "CompanySearchHitResource"
},
"DocumentDirection": {
"type": "string",
"description": "Which side of the document `own_party` is on. On a purchase invoice the own party is the buyer; on a sales invoice it is the seller.\n",
"enum": [
"purchase",
"sales"
],
"title": "DocumentDirection"
},
"DocumentListItemResource": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"object": {
"type": "string",
"const": "document"
},
"status": {
"type": "string",
"enum": [
"queued",
"extracting",
"awaiting_review",
"in_review",
"completed",
"failed",
"rejected"
]
},
"processing": {
"type": "string",
"enum": [
"automatic",
"verified"
]
},
"reference": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"file": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"mime_type": {
"type": "string"
},
"size_bytes": {
"type": "integer"
},
"pages": {
"type": [
"integer",
"null"
]
},
"sha256": {
"type": "string"
}
},
"required": [
"name",
"mime_type",
"size_bytes",
"pages",
"sha256"
]
},
"failure": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": [
"string",
"null"
]
}
},
"required": [
"code"
]
},
"rejection": {
"type": [
"object",
"null"
],
"properties": {
"reason": {
"type": [
"string",
"null"
],
"enum": [
"not_readable",
"not_an_invoice",
"multiple_documents",
"invoice_requirements",
"duplicate",
"currency_not_accepted",
null
]
}
},
"required": [
"reason"
]
},
"charge": {
"type": "object",
"properties": {
"operation": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"amount": {
"type": "string"
},
"currency": {
"type": "string"
},
"live_amount": {
"type": "string"
}
},
"required": [
"operation",
"status",
"amount",
"currency"
]
},
"expected_ready_at": {
"type": [
"string",
"null"
]
},
"created_at": {
"type": "string"
},
"completed_at": {
"type": [
"string",
"null"
]
},
"content_available": {
"type": "boolean"
}
},
"required": [
"id",
"object",
"status",
"processing",
"reference",
"metadata",
"file",
"failure",
"rejection",
"charge",
"expected_ready_at",
"created_at",
"completed_at",
"content_available"
],
"title": "DocumentListItemResource"
},
"DocumentProcessing": {
"type": "string",
"description": "How a document is processed: `automatic`, read by OCR only, or `verified`, read and then checked by a processor within 24 working hours.\n",
"enum": [
"automatic",
"verified"
],
"title": "DocumentProcessing"
},
"DocumentResource": {
"type": "object",
"properties": {
"id": {
"type": "string",
"examples": [
"doc_01jbx6y4q9t2m8rz1v3k5n7p0a"
]
},
"object": {
"type": "string",
"const": "document"
},
"status": {
"type": "string",
"description": "`queued`, `extracting`, `awaiting_review`, `in_review`, `completed`, `failed` or `rejected`.",
"enum": [
"queued",
"extracting",
"awaiting_review",
"in_review",
"completed",
"failed",
"rejected"
]
},
"processing": {
"type": "string",
"enum": [
"automatic",
"verified"
]
},
"environment": {
"type": "string",
"enum": [
"live",
"test"
]
},
"reference": {
"type": [
"string",
"null"
]
},
"metadata": {
"type": "object",
"additionalProperties": {
"type": "string"
}
},
"file": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
]
},
"mime_type": {
"type": "string"
},
"size_bytes": {
"type": "integer"
},
"pages": {
"type": [
"integer",
"null"
]
},
"sha256": {
"type": "string"
}
},
"required": [
"name",
"mime_type",
"size_bytes",
"pages",
"sha256"
]
},
"duplicate_of": {
"type": [
"string",
"null"
],
"description": "Set when this answer is an earlier document with the same file: then it is that document's own id, and nothing was charged."
},
"expected_ready_at": {
"type": [
"string",
"null"
],
"description": "`automatic`: intake plus two minutes. `verified`: the deadline, 24 working hours after intake."
},
"created_at": {
"type": "string"
},
"extracted_at": {
"type": [
"string",
"null"
]
},
"completed_at": {
"type": [
"string",
"null"
]
},
"failure": {
"type": [
"object",
"null"
],
"description": "Only with `failed`: `extraction_failed`, `provider_unavailable` or `document_unreadable`.",
"properties": {
"code": {
"type": [
"string",
"null"
]
}
},
"required": [
"code"
]
},
"result": {
"type": [
"object",
"null"
],
"description": "What was read, in the line of EN 16931. With `verified`, the values the processor checked. Null until the document is read, and after the retention period.",
"additionalProperties": {}
},
"confidence": {
"type": [
"object",
"null"
],
"description": "The confidence of the document and per field. Not calibrated: use it to sort, not as a probability.",
"properties": {
"document": {
"type": "number"
},
"fields": {
"type": "object",
"additionalProperties": {
"type": [
"number",
"null"
]
}
}
},
"required": [
"document",
"fields"
]
},
"warnings": {
"type": "array",
"description": "`totals_do_not_reconcile`, `vat_breakdown_derived`, `roles_swapped`, `multiple_documents_suspected`, `text_truncated`, `extraction_failed`.",
"items": {
"type": "string"
}
},
"verification": {
"type": [
"object",
"null"
],
"description": "Only `verified`: whether a processor checked the document, and which fields of `result` were not checked (they are as the OCR read them): the customer, the lines and the supplier's website.",
"properties": {
"verified": {
"type": "boolean"
},
"verified_at": {
"type": [
"string",
"null"
]
},
"unverified_fields": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"verified",
"verified_at",
"unverified_fields"
]
},
"rejection": {
"type": [
"object",
"null"
],
"description": "Only with `rejected`: why.",
"properties": {
"reason": {
"type": [
"string",
"null"
],
"enum": [
"not_readable",
"not_an_invoice",
"multiple_documents",
"invoice_requirements",
"duplicate",
"currency_not_accepted",
null
]
},
"message": {
"type": [
"string",
"null"
]
}
},
"required": [
"reason",
"message"
]
},
"ubl": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "Whether `GET /v1/documents/{id}/ubl` returns a file now. False before `completed`, after the retention period, and when no UBL could be made (see `errors`)."
},
"href": {
"type": "string"
},
"valid": {
"type": [
"boolean",
"null"
],
"description": "The outcome of the validation, once the UBL was made."
},
"profile": {
"type": "string",
"const": "peppol-bis-billing-3.0"
},
"errors": {
"type": "array",
"description": "The validation errors, per rule.",
"items": {
"type": "object",
"properties": {
"rule": {
"type": "string"
},
"level": {
"type": "string"
},
"location": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"rule",
"level",
"location",
"message"
]
}
}
},
"required": [
"available",
"href",
"valid",
"profile",
"errors"
]
},
"charge": {
"type": "object",
"description": "What the document costs: `reserved` while it is processed, `captured` at the outcome, `released` when it costs nothing. With a test key `amount` is always `0.0000` and `live_amount` shows the live price.",
"properties": {
"operation": {
"type": [
"string",
"null"
]
},
"status": {
"type": "string"
},
"amount": {
"type": "string"
},
"currency": {
"type": "string"
},
"live_amount": {
"type": "string"
}
},
"required": [
"operation",
"status",
"amount",
"currency"
]
},
"content_available": {
"type": "boolean",
"description": "False after the retention period or a deletion: the metadata stays, the content is gone."
},
"content_purged_at": {
"type": [
"string",
"null"
]
},
"retention_until": {
"type": [
"string",
"null"
],
"description": "When the content will be deleted. Set at the outcome."
},
"boxes": {
"type": "string"
}
},
"required": [
"id",
"object",
"status",
"processing",
"environment",
"reference",
"metadata",
"file",
"duplicate_of",
"expected_ready_at",
"created_at",
"extracted_at",
"completed_at",
"failure",
"result",
"confidence",
"warnings",
"verification",
"rejection",
"ubl",
"charge",
"content_available",
"content_purged_at",
"retention_until",
"boxes"
],
"title": "DocumentResource"
},
"DocumentStatus": {
"type": "string",
"description": "The status of a document. automatic: queued \u2192 extracting \u2192 completed | failed verified: queued \u2192 extracting \u2192 awaiting_review \u21c4 in_review \u2192 completed | rejected\n",
"enum": [
"queued",
"extracting",
"awaiting_review",
"in_review",
"completed",
"failed",
"rejected"
],
"title": "DocumentStatus"
},
"DocumentType": {
"type": "string",
"description": "The `type` hint of `POST /v1/documents`. Only a hint: it is stored, not passed to the model (a prompt change needs an evaluation first).\n",
"enum": [
"purchase_invoice",
"receipt",
"auto"
],
"title": "DocumentType"
},
"FormatAddressRequest": {
"type": "object",
"properties": {
"address": {
"type": "object",
"description": "The address: `country` (ISO 3166-1 alpha-2) and the fields of that\ncountry's address form, by field `id`. Get the form from\n`GET /v1/address/forms/{country}`.",
"examples": [
{
"country": "NL",
"street": "Hoofdstraat",
"house_number": "12",
"postal_code": "1234ab",
"city": "Amsterdam"
}
],
"properties": {
"country": {
"type": "string",
"enum": [
"AE",
"AT",
"BE",
"BG",
"CH",
"CY",
"CZ",
"DE",
"DK",
"EE",
"ES",
"FI",
"FR",
"GB",
"GR",
"HR",
"HU",
"IE",
"IS",
"IT",
"LI",
"LT",
"LU",
"LV",
"MT",
"NL",
"NO",
"PL",
"PT",
"RO",
"SE",
"SI",
"SK",
"TR"
]
}
},
"required": [
"country"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
},
"from_country": {
"type": [
"string",
"null"
],
"description": "The country the letter is sent from. When it differs from the\naddress's country, the country line is added. Leave it out for\na domestic address.",
"pattern": "^[A-Za-z]{2}$",
"examples": [
"NL"
]
},
"locale": {
"type": [
"string",
"null"
],
"description": "The language of the country line, as a language code.",
"pattern": "^[a-z]{2,3}(-[A-Z]{2})?$",
"examples": [
"en"
]
}
},
"required": [
"address"
],
"title": "FormatAddressRequest"
},
"MeResource": {
"type": "object",
"properties": {
"account": {
"type": "object",
"properties": {
"id": {
"type": "string",
"examples": [
"acc_01jbxk3v6c9m2q8r4t5w7y0z1a"
]
},
"name": {
"type": "string"
},
"status": {
"type": "string",
"description": "`pending` until the company is verified, then `active`.",
"enum": [
"pending",
"active",
"suspended",
"closed"
]
}
},
"required": [
"id",
"name",
"status"
]
},
"environment": {
"type": "string",
"description": "`live` or `test`: test calls are free and never reach a provider.",
"enum": [
"live",
"test"
]
},
"api_key": {
"type": "object",
"properties": {
"id": {
"type": "string",
"examples": [
"key_01jbxk3v6c9m2q8r4t5w7y0z1a"
]
},
"name": {
"type": "string"
},
"prefix": {
"type": "string",
"examples": [
"ac_test_Xb3k"
]
},
"expires_at": {
"type": [
"string",
"null"
]
}
},
"required": [
"id",
"name",
"prefix",
"expires_at"
]
},
"scopes": {
"type": "array",
"description": "What this key may call: `*` for everything, a product (`address`) or an operation (`address.forms`).",
"items": {
"type": "string"
}
},
"balance": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"description": "The prepaid credit, as a decimal string.",
"examples": [
"12.50"
]
},
"currency": {
"type": "string",
"const": "EUR"
}
},
"required": [
"amount",
"currency"
]
}
},
"required": [
"account",
"environment",
"api_key",
"scopes",
"balance"
],
"title": "MeResource"
},
"PricingResource": {
"type": "object",
"properties": {
"currency": {
"type": "string",
"examples": [
"EUR"
]
},
"vat_included": {
"type": "boolean",
"description": "Prices exclude VAT."
},
"base_subscription": {
"type": [
"object",
"null"
],
"description": "The monthly base subscription of a live account. It starts with the first paid top-up and is charged per day. Calls are priced on top. `name`, `product_name` and `description` are in the language of `locale`.",
"properties": {
"operation": {
"type": "string"
},
"product": {
"type": "string"
},
"product_name": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string"
},
"unit": {
"type": "string"
},
"asynchronous": {
"type": "boolean"
},
"prices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variant": {
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
"price": {
"type": [
"string",
"null"
]
},
"monthly_price": {
"type": [
"string",
"null"
]
},
"unit": {
"type": [
"string",
"null"
]
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"up_to": {
"type": [
"integer",
"null"
]
},
"price": {
"type": "string"
}
},
"required": [
"up_to",
"price"
]
}
},
"valid_from": {
"type": "string"
}
},
"required": [
"variant",
"model",
"price",
"monthly_price",
"unit",
"tiers",
"valid_from"
]
}
}
},
"required": [
"operation",
"product",
"product_name",
"name",
"description",
"status",
"unit",
"asynchronous",
"prices"
]
},
"operations": {
"type": "array",
"description": "Every operation with its price, with its name and description in the language of `locale`. `model` is `per_call` (a price per call, optionally tiered on the monthly volume) or `per_unit_month` (a monthly price per unit). An operation can have priced `variant`s, for example data from our cache and live data from the source. Test keys are always free.",
"items": {
"type": "object",
"properties": {
"operation": {
"type": "string"
},
"product": {
"type": "string"
},
"product_name": {
"type": "string"
},
"name": {
"type": "string"
},
"description": {
"type": "string"
},
"status": {
"type": "string"
},
"unit": {
"type": "string"
},
"asynchronous": {
"type": "boolean"
},
"prices": {
"type": "array",
"items": {
"type": "object",
"properties": {
"variant": {
"type": [
"string",
"null"
]
},
"model": {
"type": "string"
},
"price": {
"type": [
"string",
"null"
]
},
"monthly_price": {
"type": [
"string",
"null"
]
},
"unit": {
"type": [
"string",
"null"
]
},
"tiers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"up_to": {
"type": [
"integer",
"null"
]
},
"price": {
"type": "string"
}
},
"required": [
"up_to",
"price"
]
}
},
"valid_from": {
"type": "string"
}
},
"required": [
"variant",
"model",
"price",
"monthly_price",
"unit",
"tiers",
"valid_from"
]
}
}
},
"required": [
"operation",
"product",
"product_name",
"name",
"description",
"status",
"unit",
"asynchronous",
"prices"
]
}
},
"generated_at": {
"type": "string",
"examples": [
"2026-11-03T14:20:41Z"
]
}
},
"required": [
"currency",
"vat_included",
"base_subscription",
"operations",
"generated_at"
],
"title": "PricingResource"
},
"Problem": {
"type": "object",
"description": "An error, as RFC 9457 `application/problem+json`. Branch on `code`; it never changes for a given error.",
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "A page that explains this error.",
"examples": [
"https://docs.accountcloud.io/errors/invalid_api_key"
]
},
"title": {
"type": "string",
"description": "A short summary of the error type.",
"examples": [
"Invalid API key"
]
},
"status": {
"type": "integer",
"description": "The HTTP status code.",
"examples": [
401
]
},
"detail": {
"type": "string",
"description": "What went wrong in this case, for a human."
},
"code": {
"type": "string",
"description": "The stable, machine-readable error code.",
"enum": [
"bad_request",
"unauthenticated",
"invalid_api_key",
"api_key_expired",
"ip_not_allowed",
"account_inactive",
"account_disabled",
"insufficient_scope",
"forbidden",
"not_found",
"method_not_allowed",
"conflict",
"idempotency_key_reused",
"idempotency_key_in_use",
"invalid_idempotency_key",
"invalid_entity_reference",
"validation_failed",
"rate_limit_exceeded",
"daily_quota_exceeded",
"request_failed",
"server_error",
"api_unavailable",
"product_unavailable",
"operation_unavailable",
"service_unavailable",
"insufficient_credits",
"subscription_ended",
"monthly_cap_reached",
"provider_unavailable",
"test_mode_not_supported",
"country_not_supported",
"file_missing",
"file_too_large",
"unsupported_media_type",
"invalid_base64",
"encrypted_pdf",
"too_many_pages",
"invalid_option",
"verified_not_enabled",
"verified_daily_limit",
"document_not_found",
"document_not_ready",
"document_rejected",
"content_purged",
"feedback_window_closed",
"file_hash_mismatch",
"unknown_field",
"feedback_limit_reached",
"company_not_found",
"company_not_cached",
"register_restricted"
]
},
"request_id": {
"type": "string",
"description": "The id of the request. Quote it when you contact support.",
"examples": [
"req_01jbxk3v6c9m2q8r4t5w7y0z1a"
]
},
"errors": {
"type": "object",
"description": "With `validation_failed`: the messages per field.",
"additionalProperties": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required_scope": {
"type": "string",
"description": "With `insufficient_scope`: the scope the operation needs."
},
"granted_scopes": {
"type": "array",
"description": "With `insufficient_scope`: the scopes your key has.",
"items": {
"type": "string"
}
},
"price": {
"type": "string",
"description": "With `insufficient_credits`: what the call costs, in euros.",
"examples": [
"0.0350"
]
},
"available": {
"type": "string",
"description": "With `insufficient_credits`: the credit you have available, in euros.",
"examples": [
"0.01"
]
},
"currency": {
"type": "string",
"description": "With `insufficient_credits`: the currency of `price` and `available`.",
"examples": [
"EUR"
]
}
},
"required": [
"type",
"title",
"status",
"detail",
"code",
"request_id"
],
"title": "Problem"
},
"StoreDocumentRequest": {
"type": "object",
"description": "A document, as JSON with base64 or as multipart with the same fields.",
"properties": {
"file": {
"description": "The document: a JSON object with `name` and `content_base64`, or (multipart/form-data) a file field. A PDF, JPEG or PNG of at most 10 MB.",
"anyOf": [
{
"type": "string",
"format": "binary",
"contentMediaType": "application/octet-stream"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
},
"processing": {
"anyOf": [
{
"description": "`automatic` (default): read by OCR. `verified`: read, then checked by a processor within 24 working hours.",
"$ref": "#/components/schemas/DocumentProcessing"
},
{
"type": "null"
}
]
},
"type": {
"anyOf": [
{
"description": "A hint: `purchase_invoice`, `receipt` or `auto` (default).",
"$ref": "#/components/schemas/DocumentType"
},
{
"type": "null"
}
]
},
"direction": {
"anyOf": [
{
"description": "`purchase` (default) or `sales`. With `sales`, `own_party` is the seller.",
"$ref": "#/components/schemas/DocumentDirection"
},
{
"type": "null"
}
]
},
"output": {
"type": [
"array",
"null"
],
"description": "`[\"json\"]` (default) or `[\"json\", \"ubl\"]`: with `ubl` the UBL is made and validated when the document completes.",
"items": {
"type": "string",
"enum": [
"json",
"ubl"
]
},
"maxItems": 2
},
"country_hint": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2. A hint.",
"minLength": 2,
"maxLength": 2
},
"own_party": {
"type": [
"object",
"null"
],
"description": "The party the document is processed for. Tells the supplier and the customer apart, and becomes the buyer (or, with `sales`, the seller) in the UBL.",
"properties": {
"name": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"vat_number": {
"type": [
"string",
"null"
],
"maxLength": 32
},
"registration_number": {
"type": [
"string",
"null"
],
"maxLength": 32
},
"country_code": {
"type": [
"string",
"null"
],
"minLength": 2,
"maxLength": 2
},
"street": {
"type": [
"string",
"null"
],
"maxLength": 255
},
"house_number": {
"type": [
"string",
"null"
],
"maxLength": 32
},
"postal_code": {
"type": [
"string",
"null"
],
"maxLength": 16
},
"city": {
"type": [
"string",
"null"
],
"maxLength": 255
}
}
},
"accepted_currencies": {
"type": [
"array",
"null"
],
"description": "ISO 4217 codes. With `verified`, a document in another currency is rejected with `currency_not_accepted`.",
"items": {
"type": "string",
"minLength": 3,
"maxLength": 3
},
"maxItems": 20
},
"reference": {
"type": [
"string",
"null"
],
"description": "Your own id for the document, at most 255 characters. Filterable in the list.",
"maxLength": 255
},
"metadata": {
"type": [
"array",
"null"
],
"description": "Up to 20 keys with text values of at most 500 characters. Comes back unchanged on the document and in every webhook.",
"items": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"maxItems": 20
}
},
"required": [
"file"
],
"title": "StoreDocumentRequest"
},
"SubmitFeedbackRequest": {
"type": "object",
"description": "A report that the OCR read a document wrong.",
"properties": {
"result": {
"type": [
"string",
"null"
],
"description": "Always `incorrect`: the OCR read something wrong.",
"enum": [
"incorrect",
null
]
},
"fields": {
"type": [
"array",
"null"
],
"description": "Which fields were wrong, as paths of the result (`totals.vat_amount`), with the value you expected.",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"maxLength": 100
},
"expected": {
"type": [
"string",
"null"
],
"maxLength": 500
}
},
"required": [
"field"
]
},
"maxItems": 50
},
"comment": {
"type": [
"string",
"null"
],
"maxLength": 2000
},
"allow_training": {
"type": "boolean",
"description": "Required. `true` lets us add the document to the set we test and improve the OCR with; `false` keeps only the report, without the document."
},
"file": {
"type": [
"object",
"null"
],
"description": "Only needed when the original is already deleted: the same file again, base64.",
"properties": {
"content_base64": {
"type": "string"
}
}
}
},
"required": [
"allow_training"
],
"title": "SubmitFeedbackRequest"
},
"ValidateAddressRequest": {
"type": "object",
"properties": {
"address": {
"type": "object",
"description": "The address: `country` (ISO 3166-1 alpha-2) and the fields of that\ncountry's address form, by field `id`. Get the form from\n`GET /v1/address/forms/{country}`.",
"examples": [
{
"country": "NL",
"street": "Hoofdstraat",
"house_number": "12",
"postal_code": "1234ab",
"city": "Amsterdam"
}
],
"properties": {
"country": {
"type": "string",
"enum": [
"AE",
"AT",
"BE",
"BG",
"CH",
"CY",
"CZ",
"DE",
"DK",
"EE",
"ES",
"FI",
"FR",
"GB",
"GR",
"HR",
"HU",
"IE",
"IS",
"IT",
"LI",
"LT",
"LU",
"LV",
"MT",
"NL",
"NO",
"PL",
"PT",
"RO",
"SE",
"SI",
"SK",
"TR"
]
}
},
"required": [
"country"
],
"additionalProperties": {
"type": [
"string",
"null"
]
}
}
},
"required": [
"address"
],
"title": "ValidateAddressRequest"
},
"ValidateUblRequest": {
"type": "object",
"description": "`POST /v1/ubl/validate`: a UBL file as base64 JSON or multipart, at most 10 MB.",
"properties": {
"file": {
"description": "The UBL file: a JSON object with `content_base64`, or (multipart/form-data) a file field. At most 10 MB.",
"anyOf": [
{
"type": "string",
"format": "binary",
"contentMediaType": "application/octet-stream"
},
{
"type": "array",
"items": {
"type": "string"
}
}
]
}
},
"required": [
"file"
],
"title": "ValidateUblRequest"
},
"VatNumberResource": {
"type": "object",
"properties": {
"object": {
"type": "string",
"const": "vat_number"
},
"vat_number": {
"type": "string",
"description": "The number as VIES knows it: upper case, without separators, with its prefix (`EL` for Greece).",
"examples": [
"NL123456789B01"
]
},
"country": {
"type": "string",
"description": "ISO 3166-1 alpha-2, and `XI` for Northern Ireland.",
"examples": [
"NL"
]
},
"valid": {
"type": "boolean",
"description": "Whether VIES confirms the number."
},
"format_valid": {
"type": "boolean",
"description": "Whether the number has the format of its country. When it has not, VIES was not asked and nothing is charged."
},
"name": {
"type": [
"string",
"null"
],
"description": "The name the member state registered, when it shares it."
},
"address": {
"type": [
"string",
"null"
],
"description": "The address the member state registered, when it shares it. Lines are separated by `\\n`."
},
"consultation_number": {
"type": [
"string",
"null"
],
"description": "The consultation number VIES gave for this check: proof that the number was checked at `source.retrieved_at`. Keep it with the invoice.",
"examples": [
"WAPIAAAAZ7A9DSRB"
]
},
"source": {
"type": [
"object",
"null"
],
"description": "Where the answer comes from; null when the format was wrong and VIES was not asked.",
"properties": {
"register": {
"type": "string"
},
"name": {
"type": "string"
},
"retrieved_at": {
"type": "string"
}
},
"required": [
"register",
"name",
"retrieved_at"
]
}
},
"required": [
"object",
"vat_number",
"country",
"valid",
"format_valid",
"name",
"address",
"consultation_number",
"source"
],
"title": "VatNumberResource"
}
}
}
}