Raccoon API reference
API docs by Redocly

Raccoon ERP API (1.0.0)

Multi-tenant SaaS REST API for Raccoon, the agentic cloud ERP for small and medium businesses: business partners, products, invoices, files and tax. Authentication uses JWT Bearer tokens.

Conventions

  • Resource paths are versioned and plural — /resource/v{n}/{objects}.
  • A link to another object is an embedded reference, never a bare id — { "_id", "_class", "_name" }. Only _id is required on input; _name is a read-only display label the API composes on output.
  • DELETE responses are always 204 No Content with an empty body — including soft-deletes, cancellations, and "reset to default" semantics. Clients that need the post-deletion state must re-fetch.

Auth

Register a new tenant and admin user

Request Body schema: application/json
required
tenant_name
required
string non-empty
admin_email
required
string <email>
admin_password
required
string <password> >= 8 characters
admin_first_name
required
string non-empty
admin_last_name
required
string non-empty
required
object (RegisterAddress)

Address block on the registration payload. Used by the post- registration seed (Phase D) to build the starter Company and sample customers. Tax IDs (VAT, legal/tax registration, IBAN) are NOT accepted on the form — they are filled with country-prefix placeholders (DEXXXXXXXXX, etc.) by the seed; the user replaces them in Settings → Companies before issuing real invoices.

invite_code
required
string [ 1 .. 40 ] characters

A registration invite, issued by a Raccoon administrator. Registration is closed without one. Matched case-insensitively and ignoring whitespace; an unknown, revoked, expired or used-up code is rejected with 422.

Responses

Response Schema: application/json
required
object (ReferenceValue)

Stored value for a field of type "reference"

user_id
required
string
access_token
required
string
refresh_token
required
string
token_type
required
string
expires_in
required
integer
auth_source
required
string
Enum: "login" "api_key"

Indicates how this session was authenticated. login for email + password, api_key when the caller exchanged an API key for the token pair. The flag is propagated through refresh; clients use it to disable actions that must not chain off an API-key session (e.g. creating another API key).

Request samples

Content type
application/json
{
  • "tenant_name": "Acme GmbH",
  • "admin_email": "admin@acme.de",
  • "admin_password": "pa$$word",
  • "admin_first_name": "Jane",
  • "admin_last_name": "Doe",
  • "address": {
    },
  • "invite_code": "RCCN-7K3P-QX92"
}

Response samples

Content type
application/json
{
  • "tenant": {
    },
  • "user_id": "usr_def456",
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "auth_source": "login"
}

Authenticate and obtain tokens

Request Body schema: application/json
required
email
string <email>
password
string <password>
api_key
string

Raw API key string (rccn_{key_id}_{secret}). When present, email and password are ignored. The returned token pair carries auth_source: api_key.

Responses

Response Schema: application/json
required
object (ReferenceValue)

Stored value for a field of type "reference"

user_id
required
string
access_token
required
string
refresh_token
required
string
token_type
required
string
expires_in
required
integer
auth_source
required
string
Enum: "login" "api_key"

Indicates how this session was authenticated. login for email + password, api_key when the caller exchanged an API key for the token pair. The flag is propagated through refresh; clients use it to disable actions that must not chain off an API-key session (e.g. creating another API key).

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "api_key": "string"
}

Response samples

Content type
application/json
{
  • "tenant": {
    },
  • "user_id": "usr_def456",
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "auth_source": "login"
}

Rotate refresh token and obtain new token pair

Request Body schema: application/json
required
refresh_token
required
string

Responses

Response Schema: application/json
required
object (ReferenceValue)

Stored value for a field of type "reference"

user_id
required
string
access_token
required
string
refresh_token
required
string
token_type
required
string
expires_in
required
integer
auth_source
required
string
Enum: "login" "api_key"

Indicates how this session was authenticated. login for email + password, api_key when the caller exchanged an API key for the token pair. The flag is propagated through refresh; clients use it to disable actions that must not chain off an API-key session (e.g. creating another API key).

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "tenant": {
    },
  • "user_id": "usr_def456",
  • "access_token": "string",
  • "refresh_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 900,
  • "auth_source": "login"
}

Revoke refresh token (logout)

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Email a time-limited password-reset link

Always returns 200 regardless of whether email matches a registered, active user — this prevents callers from using the response to enumerate registered accounts.

Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Consume a reset-link token and set a new password

Single-use: the token is invalidated on first use whether or not the password update succeeds. On success, every outstanding refresh token for the user is revoked.

Request Body schema: application/json
required
token
required
string

The signed, single-use token from the reset-link email.

new_password
required
string <password> >= 8 characters

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "new_password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

API Keys

List the calling user's API keys

Returns the API keys owned by the authenticated user (never another user's keys). The bcrypt hash is never returned — only safe metadata.

Authorizations:
BearerAuth

Responses

Response Schema: application/json
required
Array of objects (ApiKeyResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a new API key for the calling user

The raw key string is returned in the key field exactly once and cannot be recovered. Only a bcrypt hash of the secret portion (salt embedded) is persisted.

Forbidden when the calling session was itself authenticated with an API key (auth_source == "api_key") — preventing privilege chaining. An API key inherits the privileges of the owning user, so the role of the resulting session matches the user's role.

Authorizations:
BearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Responses

Response Schema: application/json
key_id
required
string
key
required
string

The raw key string in the form rccn_{key_id}_{secret}. Pass this verbatim in POST /auth/login body field api_key to exchange it for a JWT pair (see LoginRequest).

name
required
string
created_at
required
integer
Reference (object) or null

Reference to the user who created the key.

Request samples

Content type
application/json
{
  • "name": "CI deploy key"
}

Response samples

Content type
application/json
{
  • "key_id": "a1b2c3d4e5f6",
  • "key": "rccn_a1b2c3d4e5f6_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  • "name": "CI deploy key",
  • "created_at": 1748815200,
  • "created_by": {
    }
}

Get a single API key (metadata only)

Authorizations:
BearerAuth
path Parameters
key_id
required
string

Short identifier embedded in the raw key string.

Responses

Response Schema: application/json
key_id
required
string

Short identifier embedded in the raw key string.

name
required
string
created_at
required
integer

Unix epoch seconds.

last_used_at
integer or null

Unix epoch seconds of the most recent successful exchange of this API key for a JWT pair at POST /auth/auth. Stays unchanged for subsequent requests within the same JWT session.

Reference (object) or null

Reference to the user who created the key. Carries the user display name denormalized at creation time. Null when the creator could not be resolved.

Response samples

Content type
application/json
{
  • "key_id": "a1b2c3d4e5f6",
  • "name": "CI deploy key",
  • "created_at": 1748815200,
  • "last_used_at": 0,
  • "created_by": {
    }
}

Revoke an API key

Authorizations:
BearerAuth
path Parameters
key_id
required
string

Short identifier embedded in the raw key string.

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Business Partners

List business partners (paginated)

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

partner_type
string
Enum: "person" "company"
status
string
Enum: "active" "inactive"
q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of any (BusinessPartnerResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a business partner

Authorizations:
BearerAuth
Request Body schema: application/json
required
partner_type
required
string
first_name
required
string non-empty
last_name
required
string non-empty
phone
string
mobile
string
email
string <email>
website
string <uri>
notes
string
status
string
Default: "active"
Enum: "active" "inactive"
language_code
string [ 2 .. 5 ] characters
Default: "en"
discount_percent
number [ 0 .. 100 ]
Default: 0

Per-partner discount applied to product list prices on Order-to-Cash documents. Defaults to 0 (no discount). 0 % is semantically the "no override" state.

payment_due_days
integer or null >= 0

Calendar days from order date to payment due date. null (or absent) means inherit default_payment_due_days from the partner type.

object or null

Reference to the BP's preferred invoice (billing) address. Must point at an address belonging to this BP that has is_invoice_address: true. The server validates both invariants on write. null means no preferred address is set; the invoice form falls back to the first address with the matching role flag.

object or null

Like preferred_invoice_address but for the shipping slot.

object or null

Like preferred_invoice_address but for the service slot.

Reference (object) or null

Optional tenant-defined sales channel this partner belongs to. null means unassigned.

vat_partner_type
string
Default: "b2c"
Enum: "b2c" "b2b" "public_authority"

Buyer kind, and the first input to VAT regime resolution. b2b with a VIES-validated VAT-ID unlocks intra-EU reverse-charge. Distinct from partner_type (the person/company discriminator). The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource).

salutation
string
salutation_code
string
Enum: "frau" "herr" "divers" "mme" "m" "ms" "mr" "mx"

Machine-readable salutation feeding a future formal-greeting helper (deferred Phase 3 invoice-text epic).

date_of_birth
string <date>
gender
string
Enum: "male" "female" "other" "unknown"

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
status
required
string
Enum: "active" "inactive"
language_code
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

email_addresses
required
Array of strings <email> [ items <email > ]

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

Request samples

Content type
application/json
Example
{
  • "phone": "+49 30 123456",
  • "mobile": "+49 170 1234567",
  • "email": "user@example.com",
  • "website": "http://example.com",
  • "notes": "string",
  • "status": "active",
  • "language_code": "de",
  • "discount_percent": 10,
  • "payment_due_days": 30,
  • "preferred_invoice_address": {
    },
  • "preferred_shipping_address": {
    },
  • "preferred_service_address": {
    },
  • "channel": {
    },
  • "vat_partner_type": "b2c",
  • "partner_type": "person",
  • "salutation": "Ms.",
  • "salutation_code": "ms",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "date_of_birth": "1985-03-15",
  • "gender": "male"
}

Response samples

Content type
application/json
Example
{
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "status": "active",
  • "language_code": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c"
}

Get a business partner (includes embedded addresses)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
status
required
string
Enum: "active" "inactive"
language_code
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

email_addresses
required
Array of strings <email> [ items <email > ]

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

Response samples

Content type
application/json
Example
{
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "status": "active",
  • "language_code": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c"
}

Replace a business partner (full update)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
phone
string
mobile
string
email
string <email>
website
string <uri>
notes
string
status
string
Enum: "active" "inactive"
language_code
string
salutation
string
first_name
string
last_name
string
date_of_birth
string <date>
gender
string
Enum: "male" "female" "other" "unknown"
company_name
string
legal_form
string
tax_id
string
vat_partner_type
string
Enum: "b2c" "b2b" "public_authority"
commercial_register_number
string
type_id
string or null
schema_version
string or null
object
discount_percent
number [ 0 .. 100 ]
payment_due_days
integer or null >= 0
object or null

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

object or null

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

object or null

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

Reference (object) or null

Tenant-defined sales channel, or null to unassign.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
status
required
string
Enum: "active" "inactive"
language_code
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

email_addresses
required
Array of strings <email> [ items <email > ]

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

Request samples

Content type
application/json
{
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "website": "http://example.com",
  • "notes": "string",
  • "status": "active",
  • "language_code": "string",
  • "salutation": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "date_of_birth": "2019-08-24",
  • "gender": "male",
  • "company_name": "string",
  • "legal_form": "string",
  • "tax_id": "string",
  • "vat_partner_type": "b2c",
  • "commercial_register_number": "string",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "discount_percent": 100,
  • "payment_due_days": 0,
  • "preferred_invoice_address": {
    },
  • "preferred_shipping_address": {
    },
  • "preferred_service_address": {
    },
  • "channel": {
    }
}

Response samples

Content type
application/json
Example
{
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "status": "active",
  • "language_code": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c"
}

Partially update a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
phone
string
mobile
string
email
string <email>
website
string <uri>
notes
string
status
string
Enum: "active" "inactive"
language_code
string
salutation
string
first_name
string
last_name
string
date_of_birth
string <date>
gender
string
Enum: "male" "female" "other" "unknown"
company_name
string
legal_form
string
tax_id
string
vat_partner_type
string
Enum: "b2c" "b2b" "public_authority"
commercial_register_number
string
type_id
string or null
schema_version
string or null
object
discount_percent
number [ 0 .. 100 ]
payment_due_days
integer or null >= 0
object or null

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

object or null

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

object or null

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

Reference (object) or null

Tenant-defined sales channel, or null to unassign.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

partner_type
required
string
first_name
required
string
last_name
required
string
status
required
string
Enum: "active" "inactive"
language_code
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

required
object

Type-specific custom-field data; {} when untyped

email_addresses
required
Array of strings <email> [ items <email > ]

All e-mail addresses linked to this partner (including login users)

vat_partner_type
required
string
Enum: "b2c" "b2b" "public_authority"

Buyer kind for VAT regime resolution. The VAT-ID itself is a vat_eu identifier (see the identifiers sub-resource), not a field here.

Request samples

Content type
application/json
{
  • "phone": "string",
  • "mobile": "string",
  • "email": "user@example.com",
  • "website": "http://example.com",
  • "notes": "string",
  • "status": "active",
  • "language_code": "string",
  • "salutation": "string",
  • "first_name": "string",
  • "last_name": "string",
  • "date_of_birth": "2019-08-24",
  • "gender": "male",
  • "company_name": "string",
  • "legal_form": "string",
  • "tax_id": "string",
  • "vat_partner_type": "b2c",
  • "commercial_register_number": "string",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "discount_percent": 100,
  • "payment_due_days": 0,
  • "preferred_invoice_address": {
    },
  • "preferred_shipping_address": {
    },
  • "preferred_service_address": {
    },
  • "channel": {
    }
}

Response samples

Content type
application/json
Example
{
  • "_id": "bp_a1b2c3",
  • "_class": "business_partner",
  • "_name": "Acme Corp",
  • "partner_type": "person",
  • "first_name": "Jane",
  • "last_name": "Doe",
  • "status": "active",
  • "language_code": "string",
  • "tenant": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "data": { },
  • "email_addresses": [
    ],
  • "vat_partner_type": "b2c"
}

Soft-delete a business partner (sets status=inactive)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Grant login access to a person-type business partner (owner only)

Creates a user account linked to the business partner and sets its business_partner_role. Restricted to the tenant owner. Only person-type partners without existing login access are eligible.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
email
required
string <email>
password
required
string <password> >= 8 characters
role
string
Default: "administrator"
Value: "administrator"

Responses

Response Schema: application/json
user_id
required
string
business_partner_id
required
string
role
required
string
Value: "administrator"
email
required
string <email>
business_partner_role
required
string
Value: "administrator"

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "role": "administrator"
}

Response samples

Content type
application/json
{
  • "user_id": "string",
  • "business_partner_id": "string",
  • "role": "administrator",
  • "email": "user@example.com",
  • "business_partner_role": "administrator"
}

Revoke login access from a business partner (owner only)

Deactivates the linked user account and clears the partner's business_partner_role. Restricted to the tenant owner. The owner's own login cannot be revoked.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Addresses

List addresses for a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (AddressResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Add an address to a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
Request Body schema: application/json
required
street_line_1
required
string non-empty
city
required
string non-empty
country_code
required
string = 2 characters

ISO 3166-1 alpha-2 country code

label
string

Free-text structural label (e.g. "HQ", "Munich warehouse"). Purely descriptive — has no behaviour.

is_invoice_address
boolean
Default: false

When true, this address is eligible to fill the invoice slot on invoices for this business partner. Auto-defaults to true for the very first address created on a BP (the freelancer-friendly default).

is_shipping_address
boolean
Default: false

When true, this address is eligible to fill the shipping slot on invoices for this business partner.

is_service_address
boolean
Default: false

When true, this address is eligible to fill the service slot on invoices for this business partner.

street_line_2
string
state_province
string
postal_code
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "label": "HQ",
  • "is_invoice_address": false,
  • "is_shipping_address": false,
  • "is_service_address": false,
  • "street_line_1": "Musterstraße 1",
  • "street_line_2": "Apt 2B",
  • "city": "Berlin",
  • "state_province": "Berlin",
  • "postal_code": "10115",
  • "country_code": "DE"
}

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a specific address

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Replace an address (full update)

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6
Request Body schema: application/json
required
label
string
is_invoice_address
boolean
is_shipping_address
boolean
is_service_address
boolean
street_line_1
string
street_line_2
string
city
string
state_province
string
postal_code
string
country_code
string = 2 characters

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "label": "string",
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "street_line_2": "string",
  • "city": "string",
  • "state_province": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Partially update an address

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6
Request Body schema: application/json
required
label
string
is_invoice_address
boolean
is_shipping_address
boolean
is_service_address
boolean
street_line_1
string
street_line_2
string
city
string
state_province
string
postal_code
string
country_code
string = 2 characters

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

is_invoice_address
required
boolean
is_shipping_address
required
boolean
is_service_address
required
boolean
street_line_1
required
string
city
required
string
country_code
required
string = 2 characters
required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "label": "string",
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "street_line_2": "string",
  • "city": "string",
  • "state_province": "string",
  • "postal_code": "string",
  • "country_code": "st"
}

Response samples

Content type
application/json
{
  • "_id": "addr_a1b2c3",
  • "_class": "address",
  • "_name": "Acme Corp",
  • "business_partner": {
    },
  • "is_invoice_address": true,
  • "is_shipping_address": true,
  • "is_service_address": true,
  • "street_line_1": "string",
  • "city": "string",
  • "country_code": "st",
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Delete an address

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Example: bp_a1b2c3d4e5f6
address_id
required
string
Example: addr_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Products

List products (optionally filtered by project)

Authorizations:
BearerAuth
query Parameters
project_id
string
Example: project_id=prj_a1b2c3d4e5f6

Filter products by project ID

limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (ProductResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a product

Authorizations:
BearerAuth
Request Body schema: application/json
required
type_id
required
string [ 1 .. 100 ] characters
name
required
string [ 1 .. 200 ] characters
Reference (object) or null

Optional project to assign this product to

Reference (object) or null

Optional tenant-defined sales channel to assign this product to

schema_version
string [ 1 .. 50 ] characters
object
vat_category
string or null
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT" null

ONIX List 62 VAT category. Optional on input — defaults to the product type's recommended_vat_category, else the tenant default (vat.default_vat_category). The VAT rate is resolved per invoice.

Array of objects (PriceInput)

Inline price entries. Single-price mode (pricing_config with no flags enabled on the product type) accepts at most one entry with no scoping fields. Multi-dimension mode accepts N entries with the corresponding scoping fields populated. The service layer rejects rows whose scoping fields aren't gated by the relevant pricing_config flag.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
schema_version
required
string
name
required
string
required
object
vat_category
required
string
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT"

ONIX List 62 VAT category. The per-invoice rate is resolved from it.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
required
Array of objects (ProductSaveWarning)
Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (Price)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Request samples

Content type
application/json
{
  • "project": {
    },
  • "channel": {
    },
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "vat_category": "H",
  • "prices": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "vat_category": "H",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ],
  • "warnings": [
    ]
}

Get a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
schema_version
required
string
name
required
string
required
object
vat_category
required
string
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT"

ONIX List 62 VAT category. The per-invoice rate is resolved from it.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (Price)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "vat_category": "H",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ]
}

Partially update a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
name
string [ 1 .. 200 ] characters
object
Reference (object) or null

Sales channel to assign, or null to unassign

vat_category
string or null
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT" null

ONIX List 62 VAT category. Omit or null to leave unchanged.

type_id
string or null
schema_version
string or null
Array of objects or null (PriceInput)

Omit (or null) to leave the existing prices unchanged. Empty array to clear. Any non-empty list replaces the prices array.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
schema_version
required
string
name
required
string
required
object
vat_category
required
string
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT"

ONIX List 62 VAT category. The per-invoice rate is resolved from it.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
required
Array of objects (ProductSaveWarning)
Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (Price)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Request samples

Content type
application/json
{
  • "name": "string",
  • "data": { },
  • "channel": {
    },
  • "vat_category": "H",
  • "type_id": "string",
  • "schema_version": "string",
  • "prices": [
    ]
}

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "vat_category": "H",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ],
  • "warnings": [
    ]
}

Delete a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Assign or unassign a product's project

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null

Project reference to assign, or null to unassign

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "product"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
schema_version
required
string
name
required
string
required
object
vat_category
required
string
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT"

ONIX List 62 VAT category. The per-invoice rate is resolved from it.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
Reference (object) or null

Project this product belongs to, null if unassigned

Reference (object) or null

Sales channel this product belongs to, null if unassigned

Array of objects (Price)

Inline price entries. Empty array when no price has been assigned. Single-price mode = 0 or 1 entries, no scoping fields populated. Multi-dim mode (any pricing_config flag on) = N entries with the gated scoping fields.

Request samples

Content type
application/json
{
  • "project": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "prd_a1b2c3d4e5f6",
  • "_class": "product",
  • "_name": "Acme Corp",
  • "type_id": "toy",
  • "schema_version": "1.0.0",
  • "name": "My Product",
  • "data": { },
  • "vat_category": "H",
  • "tenant": {
    },
  • "created_at": 1672531200,
  • "updated_at": 1672531200,
  • "project": {
    },
  • "channel": {
    },
  • "prices": [
    ]
}

Append a price row to a product

Sub-resource sugar over the parent Product update. Single-price mode accepts at most one row across the product's lifetime — adding a second one returns 422 until the relevant pricing_config flag is enabled on the product type. Scoping fields (country_codes, channel, …) are rejected unless their gating flag is on.

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
required
number or string

JSON number for common cases; quoted decimal string when the value must be preserved with sub-cent precision (the client's standard JSON encoder would otherwise round-trip through IEEE-754 float before sending). The server coerces both to Decimal. See common.yaml#/schemas/MonetaryAmount for the full precision contract and client guidance.

currency
required
string = 3 characters
_id
string or null

Optional; server generates a prc_… id when omitted.

_class
string or null
Enum: "price" null

Accepted on input but ignored — the server always assigns "price".

tax_mode
string or null
Enum: "net" "gross" null
vat_category
string or null
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT" null
country_codes
Array of strings[ items = 2 characters ]
Reference (object) or null
valid_from
string or null <date>
valid_to
string or null <date>
is_campaign
boolean
Default: false
MonetaryAmount (object) or null
number or string
Default: 1
unit_of_measure
string
Default: "EA"
compute
object or null
priority
integer
Default: 0

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "price"
amount
required
number
currency
required
string = 3 characters
tax_mode
required
string
Enum: "net" "gross"
vat_category
required
string or null
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT" null

ONIX List 62 VAT category override for this row. Null inherits the Product-level vat_category. Settable only under by_country.

country_codes
required
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 codes. Empty = any. Gated by by_country.

required
Reference (object) or null

Reference to a tenant-defined Channel. Null = applies to any channel. Gated by by_channel.

valid_from
required
string or null <date>

ISO calendar date (YYYY-MM-DD), inclusive. Gated by time_validity.

valid_to
required
string or null <date>
is_campaign
required
boolean
Default: false

Gated by campaigns.

required
MonetaryAmount (object) or null
min_quantity
required
number
Default: 1

Volume-tier breakpoint. Gated by scale_prices.

unit_of_measure
required
string
Default: "EA"
compute
required
object or null

Reserved for formula_prices.

priority
required
integer
Default: 0

Tie-breaker; higher wins. Always available.

Request samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "price",
  • "amount": 12.5,
  • "currency": "EUR",
  • "tax_mode": "net",
  • "vat_category": "H",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "_id": "prc_a1b2c3d4e5f6",
  • "_class": "price",
  • "amount": 12.5,
  • "currency": "EUR",
  • "tax_mode": "net",
  • "vat_category": "H",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Replace one price row

Full replace: the body is the new row contents; the price_id stays with the row across the swap so downstream snapshots (invoice lines, change logs) keep their back-link.

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
price_id
required
string
Example: prc_a1b2c3d4e5f6
Request Body schema: application/json
required
required
number or string

JSON number for common cases; quoted decimal string when the value must be preserved with sub-cent precision (the client's standard JSON encoder would otherwise round-trip through IEEE-754 float before sending). The server coerces both to Decimal. See common.yaml#/schemas/MonetaryAmount for the full precision contract and client guidance.

currency
required
string = 3 characters
_id
string or null

Optional; server generates a prc_… id when omitted.

_class
string or null
Enum: "price" null

Accepted on input but ignored — the server always assigns "price".

tax_mode
string or null
Enum: "net" "gross" null
vat_category
string or null
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT" null
country_codes
Array of strings[ items = 2 characters ]
Reference (object) or null
valid_from
string or null <date>
valid_to
string or null <date>
is_campaign
boolean
Default: false
MonetaryAmount (object) or null
number or string
Default: 1
unit_of_measure
string
Default: "EA"
compute
object or null
priority
integer
Default: 0

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "price"
amount
required
number
currency
required
string = 3 characters
tax_mode
required
string
Enum: "net" "gross"
vat_category
required
string or null
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT" null

ONIX List 62 VAT category override for this row. Null inherits the Product-level vat_category. Settable only under by_country.

country_codes
required
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 codes. Empty = any. Gated by by_country.

required
Reference (object) or null

Reference to a tenant-defined Channel. Null = applies to any channel. Gated by by_channel.

valid_from
required
string or null <date>

ISO calendar date (YYYY-MM-DD), inclusive. Gated by time_validity.

valid_to
required
string or null <date>
is_campaign
required
boolean
Default: false

Gated by campaigns.

required
MonetaryAmount (object) or null
min_quantity
required
number
Default: 1

Volume-tier breakpoint. Gated by scale_prices.

unit_of_measure
required
string
Default: "EA"
compute
required
object or null

Reserved for formula_prices.

priority
required
integer
Default: 0

Tie-breaker; higher wins. Always available.

Request samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "price",
  • "amount": 12.5,
  • "currency": "EUR",
  • "tax_mode": "net",
  • "vat_category": "H",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Response samples

Content type
application/json
{
  • "_id": "prc_a1b2c3d4e5f6",
  • "_class": "price",
  • "amount": 12.5,
  • "currency": "EUR",
  • "tax_mode": "net",
  • "vat_category": "H",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Partially update one price row

Body is an arbitrary subset of Price fields. The service merges the patch into the existing row, re-validates the result as a PriceInput, and re-runs the prices-array validators (scoping guard, currency consistency, scoping-tuple uniqueness).

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
price_id
required
string
Example: prc_a1b2c3d4e5f6
Request Body schema: application/json
required
property name*
additional property
any

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "price"
amount
required
number
currency
required
string = 3 characters
tax_mode
required
string
Enum: "net" "gross"
vat_category
required
string or null
Enum: "H" "S" "R" "R2" "T" "Z" "EXEMPT" null

ONIX List 62 VAT category override for this row. Null inherits the Product-level vat_category. Settable only under by_country.

country_codes
required
Array of strings[ items = 2 characters ]

ISO 3166-1 alpha-2 codes. Empty = any. Gated by by_country.

required
Reference (object) or null

Reference to a tenant-defined Channel. Null = applies to any channel. Gated by by_channel.

valid_from
required
string or null <date>

ISO calendar date (YYYY-MM-DD), inclusive. Gated by time_validity.

valid_to
required
string or null <date>
is_campaign
required
boolean
Default: false

Gated by campaigns.

required
MonetaryAmount (object) or null
min_quantity
required
number
Default: 1

Volume-tier breakpoint. Gated by scale_prices.

unit_of_measure
required
string
Default: "EA"
compute
required
object or null

Reserved for formula_prices.

priority
required
integer
Default: 0

Tie-breaker; higher wins. Always available.

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
{
  • "_id": "prc_a1b2c3d4e5f6",
  • "_class": "price",
  • "amount": 12.5,
  • "currency": "EUR",
  • "tax_mode": "net",
  • "vat_category": "H",
  • "country_codes": [
    ],
  • "channel": {
    },
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "is_campaign": false,
  • "compare_at_amount": {
    },
  • "min_quantity": 1,
  • "unit_of_measure": "EA",
  • "compute": { },
  • "priority": 0
}

Remove one price row from a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
price_id
required
string
Example: prc_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Invoices

List invoices (newest first)

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

status
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
business_partner_id
string
type_id
string
q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (InvoiceResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a new invoice (starts as draft)

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

ReferenceValue (object) or null

Issuing Company (EN 16931 BG-7 Seller). Auto-resolved from the tenant's invoice-company config when omitted on create. Per the no-bare-id rule (architecture.md#Embedded References) the wire shape is the full Reference object.

Reference (object) or null

Optional tenant-defined sales channel selected for this invoice. Snapshotted on the invoice.

issue_date
string or null <date>
due_date
string or null <date>
tax_point_date
string or null <date>

EN 16931 BT-7 — value-added-tax point date.

actual_delivery_date
string or null <date>

EN 16931 BT-72 — actual delivery date.

document_type_code
string or null
Enum: "380" "381" "384" "386" "326" null

EN 16931 BT-3 (UNCL 1001). 380=commercial invoice, 381=credit note, 384=corrected invoice, 386=prepayment invoice, 326=partial invoice.

currency
string or null = 3 characters
buyer_reference
string or null

EN 16931 BT-10. Often the buyer's PO number or Leitweg-ID.

purchase_order_reference
string or null

EN 16931 BT-13.

contract_reference
string or null

EN 16931 BT-12.

project_reference
string or null

EN 16931 BT-11.

InvoicingPeriod (object) or null
BillingReference (object) or null
buyer_name
string or null

EN 16931 BT-44 — buyer name. Defaults to the partner's company/full name.

buyer_legal_registration_id
string or null

EN 16931 BT-47.

buyer_identifier
string or null

EN 16931 BT-46 — party identifier (GLN, DUNS, etc.).

buyer_vat_id
string or null

EN 16931 BT-48.

buyer_vat_id_type
string or null

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb). Defaulted from the partner's VAT-class identifier when omitted.

PartyContact (object) or null
ElectronicAddress (object) or null
Payee (object) or null
payment_means_code
string or null

EN 16931 BT-81 (UNCL 4461). Defaults from tenant config.

payment_terms_text
string or null

EN 16931 BT-20.

PaymentTerms (object) or null

Structured skonto / late-payment block. Additive to BT-20 payment_terms_text — both render when supplied.

remittance_information
string or null

EN 16931 BT-83 — payment reference / Verwendungszweck.

Array of objects (LineItemCreate)
notes
Array of strings
Default: []

EN 16931 BT-22 — invoice notes (0..n). Each entry is rendered as its own paragraph below the totals. The author handles translation; the renderer prints what is supplied.

type_id
string or null
schema_version
string or null
object
Default: {}
object

Optional. When omitted, the server snapshots the partner's preferred addresses for each slot declared by the invoice type. When supplied, the slot keys must be a subset of the invoice type's address_slots.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
payment_means_code
required
string
required
Array of objects (LineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112. BT-115 (payable_amount) equals this until prepaid / rounding ships.

required
Array of objects (VatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed by recompute_totals(); read-only on the API. The renderer prefers this persisted list over recomputation.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

PaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "tax_point_date": "2019-08-24",
  • "actual_delivery_date": "2019-08-24",
  • "document_type_code": "380",
  • "currency": "EUR",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_means_code": "string",
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [ ],
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "vat_breakdown": [
    ],
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Get invoice by ID

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
payment_means_code
required
string
required
Array of objects (LineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112. BT-115 (payable_amount) equals this until prepaid / rounding ships.

required
Array of objects (VatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed by recompute_totals(); read-only on the API. The renderer prefers this persisted list over recomputation.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

PaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Response samples

Content type
application/json
{
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "vat_breakdown": [
    ],
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Update invoice fields and/or status

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null
ReferenceValue (object) or null

Re-pick the issuing Company. Validated against the tenant's per-doc-type allowed list. Only editable while the invoice is in draft. Per the no-bare-id rule the wire shape is the full Reference object.

Reference (object) or null

Re-pick the sales channel, or null to clear. Only editable while the invoice is in draft.

issue_date
string <date>
due_date
string <date>
dunning_level
integer >= 0

Dunning escalation level (0 = none, 1..N = reminder ladder step).

tax_point_date
string <date>
actual_delivery_date
string <date>
document_type_code
string
Enum: "380" "381" "384" "386" "326"
currency
string = 3 characters
buyer_reference
string
purchase_order_reference
string
contract_reference
string
project_reference
string
object (InvoicingPeriod)

Invoice-level invoicing period (EN 16931 BG-14).

object (BillingReference)

Preceding-invoice reference (EN 16931 BG-3 / BT-25 / BT-26).

buyer_name
string
buyer_legal_registration_id
string
buyer_identifier
string
buyer_vat_id
string
buyer_vat_id_type
string

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb).

object (PartyContact)

Contact group (EN 16931 BG-6 / BG-9).

object (ElectronicAddress)

Electronic address (EN 16931 BT-34 / BT-49). scheme_id follows the EAS code list: EM = email, 9930 = German VAT, 0088 = GLN, etc.

object (Payee)

Third-party payee (EN 16931 BG-10). Populated only when the party receiving payment differs from the seller (e.g. factoring).

payment_means_code
string
payment_terms_text
string
PaymentTerms (object) or null
remittance_information
string
Array of objects (LineItemCreate)
notes
Array of strings or null

Replaces the persisted list. null / omitted = no change; [] clears the field.

status
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
type_id
string or null
schema_version
string or null
object
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
payment_means_code
required
string
required
Array of objects (LineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112. BT-115 (payable_amount) equals this until prepaid / rounding ships.

required
Array of objects (VatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed by recompute_totals(); read-only on the API. The renderer prefers this persisted list over recomputation.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

PaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "dunning_level": 0,
  • "tax_point_date": "2019-08-24",
  • "actual_delivery_date": "2019-08-24",
  • "document_type_code": "380",
  • "currency": "str",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_means_code": "string",
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [
    ],
  • "status": "draft",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "vat_breakdown": [
    ],
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Partially update invoice fields and/or status

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
Reference (object) or null
ReferenceValue (object) or null

Re-pick the issuing Company. Validated against the tenant's per-doc-type allowed list. Only editable while the invoice is in draft. Per the no-bare-id rule the wire shape is the full Reference object.

Reference (object) or null

Re-pick the sales channel, or null to clear. Only editable while the invoice is in draft.

issue_date
string <date>
due_date
string <date>
dunning_level
integer >= 0

Dunning escalation level (0 = none, 1..N = reminder ladder step).

tax_point_date
string <date>
actual_delivery_date
string <date>
document_type_code
string
Enum: "380" "381" "384" "386" "326"
currency
string = 3 characters
buyer_reference
string
purchase_order_reference
string
contract_reference
string
project_reference
string
object (InvoicingPeriod)

Invoice-level invoicing period (EN 16931 BG-14).

object (BillingReference)

Preceding-invoice reference (EN 16931 BG-3 / BT-25 / BT-26).

buyer_name
string
buyer_legal_registration_id
string
buyer_identifier
string
buyer_vat_id
string
buyer_vat_id_type
string

EN 16931 VAT scheme of buyer_vat_id — the identifier registry schema_key (e.g. vat_eu, vat_gb).

object (PartyContact)

Contact group (EN 16931 BG-6 / BG-9).

object (ElectronicAddress)

Electronic address (EN 16931 BT-34 / BT-49). scheme_id follows the EAS code list: EM = email, 9930 = German VAT, 0088 = GLN, etc.

object (Payee)

Third-party payee (EN 16931 BG-10). Populated only when the party receiving payment differs from the seller (e.g. factoring).

payment_means_code
string
payment_terms_text
string
PaymentTerms (object) or null
remittance_information
string
Array of objects (LineItemCreate)
notes
Array of strings or null

Replaces the persisted list. null / omitted = no change; [] clears the field.

status
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
type_id
string or null
schema_version
string or null
object
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
payment_means_code
required
string
required
Array of objects (LineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112. BT-115 (payable_amount) equals this until prepaid / rounding ships.

required
Array of objects (VatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed by recompute_totals(); read-only on the API. The renderer prefers this persisted list over recomputation.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

PaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Request samples

Content type
application/json
{
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "issue_date": "2019-08-24",
  • "due_date": "2019-08-24",
  • "dunning_level": 0,
  • "tax_point_date": "2019-08-24",
  • "actual_delivery_date": "2019-08-24",
  • "document_type_code": "380",
  • "currency": "str",
  • "buyer_reference": "string",
  • "purchase_order_reference": "string",
  • "contract_reference": "string",
  • "project_reference": "string",
  • "invoicing_period": {
    },
  • "preceding_invoice": {
    },
  • "buyer_name": "string",
  • "buyer_legal_registration_id": "string",
  • "buyer_identifier": "string",
  • "buyer_vat_id": "string",
  • "buyer_vat_id_type": "string",
  • "buyer_contact": {
    },
  • "buyer_electronic_address": {
    },
  • "payee": {
    },
  • "payment_means_code": "string",
  • "payment_terms_text": "string",
  • "payment_terms": {
    },
  • "remittance_information": "string",
  • "line_items": [
    ],
  • "notes": [
    ],
  • "status": "draft",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { },
  • "addresses": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "vat_breakdown": [
    ],
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Cancel an invoice (soft-delete; status → cancelled)

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Finalize invoice (draft → finalized)

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
payment_means_code
required
string
required
Array of objects (LineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112. BT-115 (payable_amount) equals this until prepaid / rounding ships.

required
Array of objects (VatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed by recompute_totals(); read-only on the API. The renderer prefers this persisted list over recomputation.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

PaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Response samples

Content type
application/json
{
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "vat_breakdown": [
    ],
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Refresh invoice address snapshots from the partner's preferred addresses

Replaces the invoice's address snapshots with the current preferred (primary) addresses from the linked business partner, for every slot declared on the invoice type. The frontend calls this after the user confirms a "Update addresses to {new partner}'s defaults?" prompt triggered by a business-partner change. Only allowed while the invoice is in draft.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label (the invoice number, or id while still a draft).

invoice_number
required
string

Empty ("") while the invoice is in draft. Stamped by the per-tenant InvoiceNumberingSchema on the draft → finalized transition (resolution order: invoice type → company → tenant-default schema). Once assigned, the value is immutable. Cancellation from draft does NOT consume a number — the row keeps the empty string and relies on status="cancelled" as the audit signal.

required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

status
required
string
Enum: "draft" "finalized" "paid" "overdue" "cancelled"
issue_date
required
string <date>
due_date
required
string <date>
document_type_code
required
string
Enum: "380" "381" "384" "386" "326"
currency
required
string
payment_means_code
required
string
required
Array of objects (LineItemResponse)
required
object (MonetaryAmount)

EN 16931 BT-109 — sum of line nets, as a MonetaryAmount carrying the invoice's currency (BT-5). A draft whose totals haven't been computed yet returns the identity element ({"amount": 0, "currency": null}).

required
object (MonetaryAmount)

EN 16931 BT-110.

required
object (MonetaryAmount)

EN 16931 BT-112. BT-115 (payable_amount) equals this until prepaid / rounding ships.

required
Array of objects (VatBreakdownLine)

Per-VAT-rate breakdown (UStG §14). Server-computed by recompute_totals(); read-only on the API. The renderer prefers this persisted list over recomputation.

notes
required
Array of strings

EN 16931 BT-22 invoice notes (0..n).

required
object
required
object

Snapshotted address per slot the invoice type declared. Slot keys are a subset of the type's address_slots (invoice | shipping | service). Empty object when no slot is configured for the invoice type or the partner has no eligible address.

created_at
required
integer
updated_at
required
integer
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

ReferenceValue (object) or null

Issuing Company (BG-7 Seller). Snapshotted onto the immutable seller_* columns at draft → finalized. Null until the auto-default resolves (Phase D seed guarantees a value for new tenants).

Reference (object) or null

Sales channel selected for this invoice, null if none.

dunning_level
integer

Dunning escalation level (0 = none, 1..N = reminder ladder step).

PaymentTerms (object) or null

Structured BT-20 sub-block. null when unset.

Response samples

Content type
application/json
{
  • "_id": "inv_a1b2c3d4e5f6",
  • "_class": "invoice",
  • "_name": "Acme Corp",
  • "invoice_number": "2026-R-0042",
  • "business_partner": {
    },
  • "company": {
    },
  • "channel": {
    },
  • "status": "draft",
  • "issue_date": "2026-05-01",
  • "due_date": "2026-05-31",
  • "dunning_level": 0,
  • "document_type_code": "380",
  • "currency": "EUR",
  • "payment_means_code": "30",
  • "line_items": [
    ],
  • "tax_exclusive": {
    },
  • "tax_total": {
    },
  • "tax_inclusive": {
    },
  • "vat_breakdown": [
    ],
  • "notes": [
    ],
  • "payment_terms": {
    },
  • "data": { },
  • "addresses": {
    },
  • "created_at": 1746144000,
  • "updated_at": 1746144000,
  • "created_by": {
    },
  • "tenant": {
    }
}

Documents

List documents for an invoice

Returns all document rows attached to the invoice. A document is a derived business document (invoice PDF, delivery slip, offer, …) generated asynchronously by a worker.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (DocumentResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a document for an invoice

Creates a document row in pdf_pending and emits a document.created event. The PDF generation worker subscribes and asynchronously attaches the rendered file — clients should poll the row until status flips to pdf_ready.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Example: inv_a1b2c3d4e5f6
Request Body schema: application/json
required
document_type
required
string (DocumentType)
Enum: "invoice" "delivery_slip" "offer" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. MVP only renders PDFs for invoice; the other values are reserved for upcoming templates.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
invoice_id
required
string
document_type
required
string (DocumentType)
Enum: "invoice" "delivery_slip" "offer" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. MVP only renders PDFs for invoice; the other values are reserved for upcoming templates.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

Request samples

Content type
application/json
{
  • "document_type": "invoice"
}

Response samples

Content type
application/json
{
  • "_id": "doc_a1b2c3d4e5f6789012345",
  • "_class": "document",
  • "invoice_id": "inv_a1b2c3d4e5f6",
  • "document_type": "invoice",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    }
}

Get a single document

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
document_id
required
string
Example: doc_a1b2c3d4e5f67890

Responses

Response Schema: application/json
_id
required
string
_class
required
string
invoice_id
required
string
document_type
required
string (DocumentType)
Enum: "invoice" "delivery_slip" "offer" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. MVP only renders PDFs for invoice; the other values are reserved for upcoming templates.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

Response samples

Content type
application/json
{
  • "_id": "doc_a1b2c3d4e5f6789012345",
  • "_class": "document",
  • "invoice_id": "inv_a1b2c3d4e5f6",
  • "document_type": "invoice",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    }
}

Partial update — typically used to attach the rendered PDF

The only mutable field today is file. Setting file on a pdf_pending document implicitly transitions it to pdf_ready — the status FSM is server-controlled and callers cannot write status directly. Used by the invoice-document-generator service to report a rendered PDF (per architecture.md § Async Workers — no internal API; a UI client could call it too). Requires admin/superuser role. Idempotent: replaying on an already-attached document returns 200 with the existing row (the originally attached PDF is preserved). Per architecture.md § Embedded References, only _id is required inside the file Reference; _class and _name are accepted and resolved server-side from the linked File row.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
document_id
required
string
Example: doc_a1b2c3d4e5f67890
Request Body schema: application/json
required
object or null

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
invoice_id
required
string
document_type
required
string (DocumentType)
Enum: "invoice" "delivery_slip" "offer" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. MVP only renders PDFs for invoice; the other values are reserved for upcoming templates.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

Request samples

Content type
application/json
{
  • "file": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "doc_a1b2c3d4e5f6789012345",
  • "_class": "document",
  • "invoice_id": "inv_a1b2c3d4e5f6",
  • "document_type": "invoice",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    }
}

Delete a document

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
document_id
required
string
Example: doc_a1b2c3d4e5f67890

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Retry a `pdf_failed` document

Moves a pdf_failed document back to pdf_pending and re-publishes the document.created event so the worker picks it up again. Idempotent for already-pending rows.

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
document_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
invoice_id
required
string
document_type
required
string (DocumentType)
Enum: "invoice" "delivery_slip" "offer" "pro_forma_invoice" "intermediate_receipt"

The kind of business document this document represents. MVP only renders PDFs for invoice; the other values are reserved for upcoming templates.

status
required
string (DocumentStatus)
Enum: "draft" "pdf_pending" "pdf_ready" "pdf_failed"

Lifecycle state. New documents start at pdf_pending; the async PDF worker promotes them to pdf_ready (or pdf_failed on permanent error). draft is reserved for future use.

required
Reference (object) or null

Reference to the rendered PDF. null until the document-generator worker reports the output via PATCH .../documents/{id}.

template_version
required
string
created_at
required
integer
updated_at
required
integer
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

Response samples

Content type
application/json
{
  • "_id": "doc_a1b2c3d4e5f6789012345",
  • "_class": "document",
  • "invoice_id": "inv_a1b2c3d4e5f6",
  • "document_type": "invoice",
  • "status": "draft",
  • "file": {
    },
  • "template_version": "1.0.0",
  • "created_at": 0,
  • "updated_at": 0,
  • "tenant": {
    }
}

Projects

List projects for the authenticated tenant

Authorizations:
BearerAuth
query Parameters
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

q
string non-empty

Full-text search term. When provided, the endpoint delegates to the shared search index (matches across name/title/email/identifier fields, tenant-scoped) and returns the matching entities in the same response shape as the unfiltered list. Pagination (limit, next_token) is not honoured in this mode; results are capped at the search index size limit (20 items in MVP).

Responses

Response Schema: application/json
required
Array of objects (ProjectResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a project

Authorizations:
BearerAuth
Request Body schema: application/json
required
title
required
string [ 1 .. 200 ] characters
description
string
type_id
string or null

Optional global or tenant type identifier (e.g. "client_project")

schema_version
string or null

Type version. Omitted = latest.

object

Custom field values keyed by section field IDs.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

title
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object

Custom field values; {} when untyped

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "title": "Q2 2026 Launch",
  • "description": "string",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_id": "prj_a1b2c3d4e5f6",
  • "_class": "project",
  • "_name": "Acme Corp",
  • "title": "string",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0
}

Get a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Example: prj_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

title
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object

Custom field values; {} when untyped

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Response samples

Content type
application/json
{
  • "_id": "prj_a1b2c3d4e5f6",
  • "_class": "project",
  • "_name": "Acme Corp",
  • "title": "string",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0
}

Partially update a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Example: prj_a1b2c3d4e5f6
Request Body schema: application/json
required
title
string [ 1 .. 200 ] characters
description
string
type_id
string or null
schema_version
string or null
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

title
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object

Custom field values; {} when untyped

created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "title": "string",
  • "description": "string",
  • "type_id": "string",
  • "schema_version": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_id": "prj_a1b2c3d4e5f6",
  • "_class": "project",
  • "_name": "Acme Corp",
  • "title": "string",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Example: prj_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Custom Objects

List a tenant type's custom objects (type-scoped, name-sorted)

Lists the custom objects of one tenant custom_object-class type. The type query parameter is required — objects are only ever viewed within their type group, and the query is strongly consistent.

Authorizations:
BearerAuth
query Parameters
type
required
string
Example: type=series
limit
integer [ 1 .. 200 ]
Default: 50
next_token
string

Base64-encoded pagination cursor from previous response

Responses

Response Schema: application/json
required
Array of objects (CustomObjectResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Create a custom object

Authorizations:
BearerAuth
Request Body schema: application/json
required
type_id
required
string [ 1 .. 100 ] characters

The tenant custom_object-class type this record is shaped by (e.g. "series").

name
required
string [ 1 .. 200 ] characters
object

Custom field values keyed by the type's section field IDs.

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "type_id": "string",
  • "name": "Studies in Modern Poetry",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0
}

Get a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Response samples

Content type
application/json
{
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0
}

Replace a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6
Request Body schema: application/json
required
type_id
string [ 1 .. 100 ] characters
name
string [ 1 .. 200 ] characters
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "type_id": "string",
  • "name": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0
}

Partially update a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6
Request Body schema: application/json
required
type_id
string [ 1 .. 100 ] characters
name
string [ 1 .. 200 ] characters
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

type_id
required
string
name
required
string
schema_version
required
string
required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object
created_at
required
integer

Unix epoch seconds

updated_at
required
integer

Unix epoch seconds

Request samples

Content type
application/json
{
  • "type_id": "string",
  • "name": "string",
  • "data": { }
}

Response samples

Content type
application/json
{
  • "_id": "cob_a1b2c3d4e5f6",
  • "_class": "custom_object",
  • "_name": "Acme Corp",
  • "type_id": "series",
  • "name": "string",
  • "schema_version": "1.0.0",
  • "tenant": {
    },
  • "data": { },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Example: cob_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Files

Issue a presigned upload form for a new file

Validates the request against the file-type registry, enforces cardinality (a cardinality: one type rejects a second active upload with HTTP 409), and returns a presigned POST form scoped to the caller's tenant prefix in S3.

After uploading the bytes via the returned upload form, an S3 event promotes the row from status=pending to ready (or failed).

Authorizations:
BearerAuth
Request Body schema: application/json
required
required
object (ReferenceValue)

Stored value for a field of type "reference"

type
required
string
file_name
required
string
file_size
required
integer >= 1
mime_type
required
string
description
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "file"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

type
required
string
file_name
required
string
file_size
required
integer
mime_type
required
string
sha256
required
string or null

Hex-encoded SHA-256, populated once status=ready.

status
required
string (FileStatus)
Enum: "pending" "ready" "quarantined" "failed" "soft_deleted"

Lifecycle state of a file. pending is set when the upload URL is issued; the S3 ObjectCreated event handler promotes to ready after validation, or to failed/quarantined if validation or malware scanning rejects the object.

retention_class
required
string
Enum: "transient" "standard" "archival"
legal_hold
required
boolean
description
required
string or null
href
required
string <uri>

Self-link to the download endpoint.

created_at
required
integer
updated_at
required
integer
required
object or null

Stored value for a field of type "reference"

required
object (PresignedPost)

S3 presigned-POST form. The client must POST multipart/form-data with every field from fields plus a final file part containing the binary body.

Request samples

Content type
application/json
{
  • "parent": {
    },
  • "type": "business_partner.avatar",
  • "file_name": "string",
  • "file_size": 1,
  • "mime_type": "image/png",
  • "description": "string"
}

Response samples

Content type
application/json
{
  • "_id": "fil_a1b2c3d4e5f6",
  • "_class": "file",
  • "_name": "Acme Corp",
  • "tenant": {
    },
  • "parent": {
    },
  • "type": "business_partner.avatar",
  • "file_name": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "sha256": "string",
  • "status": "pending",
  • "retention_class": "transient",
  • "legal_hold": true,
  • "description": "string",
  • "href": "http://example.com",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    },
  • "upload": {
    }
}

List files attached to a parent entity

Authorizations:
BearerAuth
query Parameters
parent_id
required
string
parent_class
required
string
Enum: "business_partner" "product" "project" "invoice" "tenant" "chat"
type
string

Filter by namespaced file-type key.

limit
integer <= 200
Default: 50
next_token
string

Responses

Response Schema: application/json
required
Array of objects (FileResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Get file metadata

Authorizations:
BearerAuth
path Parameters
file_id
required
string
Example: fil_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "file"
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

required
object (ReferenceValue)

Stored value for a field of type "reference"

required
object (ReferenceValue)

Stored value for a field of type "reference"

type
required
string
file_name
required
string
file_size
required
integer
mime_type
required
string
sha256
required
string or null

Hex-encoded SHA-256, populated once status=ready.

status
required
string (FileStatus)
Enum: "pending" "ready" "quarantined" "failed" "soft_deleted"

Lifecycle state of a file. pending is set when the upload URL is issued; the S3 ObjectCreated event handler promotes to ready after validation, or to failed/quarantined if validation or malware scanning rejects the object.

retention_class
required
string
Enum: "transient" "standard" "archival"
legal_hold
required
boolean
description
required
string or null
href
required
string <uri>

Self-link to the download endpoint.

created_at
required
integer
updated_at
required
integer
required
object or null

Stored value for a field of type "reference"

Response samples

Content type
application/json
{
  • "_id": "fil_a1b2c3d4e5f6",
  • "_class": "file",
  • "_name": "Acme Corp",
  • "tenant": {
    },
  • "parent": {
    },
  • "type": "business_partner.avatar",
  • "file_name": "string",
  • "file_size": 0,
  • "mime_type": "string",
  • "sha256": "string",
  • "status": "pending",
  • "retention_class": "transient",
  • "legal_hold": true,
  • "description": "string",
  • "href": "http://example.com",
  • "created_at": 0,
  • "updated_at": 0,
  • "created_by": {
    }
}

Soft-delete a file

Sets status=soft_deleted and deleted_at. The S3 object is kept for 30 days then hard-deleted by a nightly cleanup, unless the file carries legal_hold=true.

Authorizations:
BearerAuth
path Parameters
file_id
required
string
Example: fil_a1b2c3d4e5f6

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Issue a short-lived presigned download URL

Authorizations:
BearerAuth
path Parameters
file_id
required
string

Responses

Response Schema: application/json
url
required
string <uri>
expires_at
required
integer

Response samples

Content type
application/json
{}

Codelists

List codelists in the catalog (global + tenant)

Authorizations:
BearerAuth
query Parameters
scope
string
Enum: "global" "tenant"
namespace
string
industry
string
authority
string
status
string
Enum: "draft" "active" "deprecated"

Responses

Response Schema: application/json
required
Array of objects (CodelistHeader)
count
required
integer

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0
}

Get a codelist header

Authorizations:
BearerAuth
path Parameters
namespace
required
string

Codelist namespace; may contain slashes (e.g. iso/3166-1). Pass each segment as a separate path segment.

version
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

namespace
required
string
version
required
string
scope
required
string
Enum: "global" "tenant"
status
required
string
Enum: "draft" "active" "deprecated"
required
object
loading
required
string
Enum: "eager" "lazy"
authority
string
industry
Array of strings
object
is_stub
boolean
created_at
integer
updated_at
integer

Response samples

Content type
application/json
{
  • "_id": "cl_iso_3166_1_2020",
  • "_class": "codelist",
  • "_name": "Acme Corp",
  • "namespace": "iso/3166-1",
  • "version": "2020",
  • "authority": "string",
  • "industry": [
    ],
  • "scope": "global",
  • "display_name": {
    },
  • "description": {
    },
  • "loading": "eager",
  • "status": "draft",
  • "is_stub": true,
  • "created_at": 0,
  • "updated_at": 0
}

List codes in a codelist

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
query Parameters
locale
string
Default: "en"
parent_code
string
status
string
Enum: "active" "deprecated" "retired"
q
string
limit
integer
Default: 50
offset
integer
Default: 0

Responses

Response Schema: application/json
required
Array of objects (CodeValueResponse)
count
required
integer
total
required
integer

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "count": 0,
  • "total": 0
}

Get a single code

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Walk replaced_by_code chain to a terminal node

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string

Responses

Response Schema: application/json
required
object
required
Array of objects (CodeValueResponse)
required
object (CodeValueResponse)

Response samples

Content type
application/json
{
  • "from": {
    },
  • "chain": [
    ],
  • "terminal": {
    }
}

Validate a (namespace, version, code) tuple

Authorizations:
BearerAuth
Request Body schema: application/json
required
namespace
required
string
code
required
string
version
string
Default: "latest"
locale
string
Default: "en"

Responses

Response Schema: application/json
valid
required
boolean
namespace
required
string
version
required
string
code
required
string

Request samples

Content type
application/json
{
  • "namespace": "string",
  • "version": "latest",
  • "code": "string",
  • "locale": "en"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "namespace": "string",
  • "version": "string",
  • "code": "string"
}

Create a tenant codelist (slug becomes part of the namespace)

Authorizations:
BearerAuth
Request Body schema: application/json
required
slug
required
string
required
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

namespace
required
string
version
required
string
scope
required
string
Enum: "global" "tenant"
status
required
string
Enum: "draft" "active" "deprecated"
required
object
loading
required
string
Enum: "eager" "lazy"
authority
string
industry
Array of strings
object
is_stub
boolean
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "slug": "my_categories",
  • "codelist": {
    }
}

Response samples

Content type
application/json
{
  • "_id": "cl_iso_3166_1_2020",
  • "_class": "codelist",
  • "_name": "Acme Corp",
  • "namespace": "iso/3166-1",
  • "version": "2020",
  • "authority": "string",
  • "industry": [
    ],
  • "scope": "global",
  • "display_name": {
    },
  • "description": {
    },
  • "loading": "eager",
  • "status": "draft",
  • "is_stub": true,
  • "created_at": 0,
  • "updated_at": 0
}

Publish a new immutable version of a tenant codelist

Authorizations:
BearerAuth
path Parameters
namespace
required
string

Tenant codelist namespace (must start with tenant:).

Request Body schema: application/json
required
version
required
string
published_at
string <date>
authority
string
industry
Array of strings
object
object
licence
string
attribution
string
status
string
Enum: "draft" "active" "deprecated"

Responses

Response Schema: application/json
_id
required
string
_class
required
string
_name
required
string (EntityName)

Read-only, backend-composed display label of this entity (a person's full name, a product's name, a project's title, …). A backend-meta field (sibling of _id / _class) — never accepted on input.

namespace
required
string
version
required
string
scope
required
string
Enum: "global" "tenant"
status
required
string
Enum: "draft" "active" "deprecated"
required
object
loading
required
string
Enum: "eager" "lazy"
authority
string
industry
Array of strings
object
is_stub
boolean
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "version": "string",
  • "published_at": "2019-08-24",
  • "authority": "string",
  • "industry": [
    ],
  • "display_name": {
    },
  • "description": {
    },
  • "licence": "string",
  • "attribution": "string",
  • "status": "draft"
}

Response samples

Content type
application/json
{
  • "_id": "cl_iso_3166_1_2020",
  • "_class": "codelist",
  • "_name": "Acme Corp",
  • "namespace": "iso/3166-1",
  • "version": "2020",
  • "authority": "string",
  • "industry": [
    ],
  • "scope": "global",
  • "display_name": {
    },
  • "description": {
    },
  • "loading": "eager",
  • "status": "draft",
  • "is_stub": true,
  • "created_at": 0,
  • "updated_at": 0
}

Add a code to a tenant codelist

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
Request Body schema: application/json
required
code
required
string
object
object
parent_code
string
valid_from
string <date>
valid_to
string <date>
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "code": "string",
  • "display_name": {
    },
  • "description": {
    },
  • "parent_code": "string",
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Update a tenant codelist code

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string
Request Body schema: application/json
required
object
object
parent_code
string
valid_from
string <date>
valid_to
string <date>
status
string
Enum: "active" "deprecated" "retired"
replaced_by_code
string
object

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "display_name": {
    },
  • "description": {
    },
  • "parent_code": "string",
  • "valid_from": "2019-08-24",
  • "valid_to": "2019-08-24",
  • "status": "active",
  • "replaced_by_code": "string",
  • "metadata": { }
}

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a code value (only allowed while the version is unpublished)

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Mark a tenant code as deprecated

Authorizations:
BearerAuth
path Parameters
namespace
required
string
version
required
string
code
required
string
Request Body schema: application/json
optional
replaced_by_code
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
namespace
required
string
version
required
string
code
required
string
status
required
string
Enum: "active" "deprecated" "retired"
required
object
required
object (ReferenceValue)

Stored value for a field of type "reference"

object
created_at
integer
updated_at
integer

Request samples

Content type
application/json
{
  • "replaced_by_code": "string"
}

Response samples

Content type
application/json
{
  • "_id": "EUR",
  • "_class": "code_value",
  • "codelist": {
    },
  • "namespace": "string",
  • "version": "string",
  • "code": "string",
  • "display_name": {
    },
  • "status": "active",
  • "metadata": { },
  • "created_at": 0,
  • "updated_at": 0
}

Identifiers

List identifiers for a company

Authorizations:
BearerAuth
path Parameters
company_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a company

Authorizations:
BearerAuth
path Parameters
company_id
required
string
Request Body schema: application/json
required
schema_key
required
string
value
required
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "schema_key": "ean13",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a company identifier

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Update a company identifier

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a company identifier

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
company_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "applied": true
}

Cross-entity reverse lookup by identifier value

Returns all identifier records matching the given schema_key and value within the authenticated tenant. Each result contains a parent Reference pointing to the owning entity. Use the nested sub-resource endpoints for CRUD operations on identifiers.

Authorizations:
BearerAuth
query Parameters
schema_key
required
string
Example: schema_key=ean13
identifier
required
string
Example: identifier=4006381333931

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

Identifier schemas selectable for an entity class

Returns the platform identifier schemas that can be attached to the given entity class. Every scheme is returned (a company may hold a foreign VAT registration, so none are hidden); when country is supplied the scheme issued by that country (e.g. vat_eu for an EU company, vat_gb for a UK company) is sorted first and flagged recommended. Drives the add-identifier dropdown on the Company form.

Authorizations:
BearerAuth
query Parameters
entity_class
required
string
Example: entity_class=company
country
string
Example: country=DE

ISO 3166-1 alpha-2 code of the entity's home country.

Responses

Response Schema: application/json
required
Array of objects (IdentifierSchema)
next_token
required
string or null

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "string"
}

List identifiers for a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a product

Authorizations:
BearerAuth
path Parameters
product_id
required
string
Example: prd_a1b2c3d4e5f6
Request Body schema: application/json
required
schema_key
required
string
value
required
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "schema_key": "ean13",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a product identifier

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Update a product identifier

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a product identifier

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
product_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "applied": true
}

List identifiers for a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a business partner

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
Request Body schema: application/json
required
schema_key
required
string
value
required
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "schema_key": "ean13",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a business partner identifier

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Update a business partner identifier

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a business partner identifier

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Dedicated write path for async validators (e.g. the VIES worker) to report a verdict, kept off the general identifier PATCH so a worker write and a concurrent user value-edit can't clobber each other. Applies staleness + never-downgrade rules; applied=false when skipped.

Authorizations:
BearerAuth
path Parameters
business_partner_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "applied": true
}

List identifiers for an invoice

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to an invoice

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
Request Body schema: application/json
required
schema_key
required
string
value
required
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "schema_key": "ean13",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get an invoice identifier

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Update an invoice identifier

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Delete an invoice identifier

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
invoice_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "applied": true
}

List identifiers for a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a project

Authorizations:
BearerAuth
path Parameters
project_id
required
string
Request Body schema: application/json
required
schema_key
required
string
value
required
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "schema_key": "ean13",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a project identifier

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Update a project identifier

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a project identifier

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Append a validation result to an identifier (async-validator callback)

Authorizations:
BearerAuth
path Parameters
project_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
required
string

The identifier value the validator checked (staleness guard).

type
required
string
status
required
string
result
required
string
Enum: "SUCCESS" "INVALID" "UNAVAILABLE"
validated_at
required
integer
name_on_record
string or null
consultation_number
string or null
work_type
string or null

Crossref work type (e.g. journal-article) for a doi result.

log
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer
applied
required
boolean

False when the result was dropped (staleness — value changed — or never-downgrade of a cached SUCCESS); the identifier is unchanged.

Request samples

Content type
application/json
{
  • "value": "string",
  • "type": "vies",
  • "status": "completed",
  • "result": "SUCCESS",
  • "validated_at": 0,
  • "name_on_record": "string",
  • "consultation_number": "string",
  • "work_type": "string",
  • "log": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0,
  • "applied": true
}

List identifiers for a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string

Responses

Response Schema: application/json
required
Array of objects (IdentifierResponse)

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add an identifier to a custom object

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
Request Body schema: application/json
required
schema_key
required
string
value
required
string
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "schema_key": "ean13",
  • "value": "4006381333931",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Get a custom-object identifier

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
identifier_id
required
string

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Update a custom-object identifier

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
identifier_id
required
string
Request Body schema: application/json
required
value
string or null
label
string or null

Responses

Response Schema: application/json
_id
required
string
_class
required
string
required
object (Reference)

An embedded reference to another entity.

In responses all three fields are always present (the backend builds every reference from the live entity), so they are marked required. _name is a backend-meta field (sibling of _id / _class): the read-only, backend-composed display label.

In request bodies only _id is required: the backend resolves the entity from _id and derives _class and _name itself, ignoring any values the caller submits. A minimal reference is therefore {"_id": "bp_..."}. To clear a nullable reference, send null.

schema_key
required
string
value
required
string
required
Array of objects

Zero or more validation results for this identifier value, one per validator. Open shape (each is {type, status, result, ...}); VIES is the first producer. Written only by the validations-append endpoint (worker callback), never by the general identifier PATCH.

required
object (ReferenceValue)

Stored value for a field of type "reference"

created_at
required
integer
updated_at
required
integer

Request samples

Content type
application/json
{
  • "value": "string",
  • "label": "string"
}

Response samples

Content type
application/json
{
  • "_id": "string",
  • "_class": "identifier",
  • "parent": {
    },
  • "schema_key": "string",
  • "value": "string",
  • "validations": [
    ],
  • "tenant": {
    },
  • "created_at": 0,
  • "updated_at": 0
}

Delete a custom-object identifier

Authorizations:
BearerAuth
path Parameters
custom_object_id
required
string
identifier_id
required
string

Responses

Response samples

Content type
application/json
{
  • "error": "not_found",
  • "message": "Business partner not found",
  • "details": { }
}

Changes

Poll the tenant change feed

Returns the changes recorded at or after since, oldest first, so a client can refresh whatever it has on screen that appears in the result. Each entry names a subject to re-read; none carries field values.

The response's next_token is a durable cursor, not a page marker: it is never null, and the client sends it back as since on the next poll. Omitting since subscribes from now and returns an empty page — a client that has just loaded has no backlog to catch up on.

Delivery is at-least-once. The cursor lags real time by a couple of seconds so a change written late within a second cannot be skipped, which means consecutive polls re-deliver a small overlap; de-duplicate on _id. Refetching is idempotent, so this is a deliberate trade.

Authorizations:
BearerAuth
query Parameters
since
string
Example: since=1785483570

Cursor from a previous response's next_token.

limit
integer [ 1 .. 200 ]
Default: 100

Responses

Response Schema: application/json
required
Array of objects (ChangeResponse)
next_token
required
string

The feed cursor, never null — unlike every other list endpoint, where next_token marks a page. Store it and send it back as since on the next poll. It deliberately lags real time by a couple of seconds, so consecutive polls re-deliver a small overlap; de-duplicate on _id.

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_token": "1785483570"
}

Read a single change row

Authorizations:
BearerAuth
path Parameters
change_id
required
string
Example: chg_a1b2c3d4e5f6

Responses

Response Schema: application/json
_id
required
string
_class
required
string
Value: "change"
required
object (Reference)

The aggregate the client should re-read. _name is always empty — the feed never resolves it, both to keep a 200-row page to a single query and because a deleted subject no longer exists to name.

resource_class
required
string

Aggregate root class, e.g. product.

subclass
required
string

Fully-qualified path of what changed within the aggregate, e.g. product.price or business_partner.identifier.

method
required
string
Enum: "created" "updated" "deleted"
actor_kind
required
string

Who caused it — user, agent, service, or system.

created_at
required
integer

Unix epoch seconds. Also the feed's ordering position.

updated_at
required
integer

Unix epoch seconds.

object

Response samples

Content type
application/json
{
  • "_id": "chg_a1b2c3d4e5f6",
  • "_class": "change",
  • "subject": {
    },
  • "resource_class": "product",
  • "subclass": "product.price",
  • "method": "created",
  • "actor_kind": "agent",
  • "created_at": 0,
  • "updated_at": 0,
  • "_links": {
    }
}