Entities tools · Ownrecord docs

entities_create: Create a legal entity
entities_get: Get a legal entity
entities_list: List legal entities
entities_registry_extract_upload: Upload a registry extract for verification
entities_update: Update a legal entity
entities_verify: Verify a legal entity's tax ID

`entities_create`

Create a legal entity. Operation entities.create · Organization level · permission entities:write · risk tier write · since M1

Adds a legal entity: the company that sells (the seller of record), with its establishment, company registry ID, home tax ID, default currency, time zone and invoice settings. Brands are created under an entity next.

The entity starts onboarding and unverified. Its home tax ID is verified later (VIES for eu_vat, HMRC for gb_vat, CH UID for ch_vat, otherwise a registry extract reviewed by Ownrecord). Invoice settings default to the number format {series}-{year}-{seq:06}, a yearly sequence reset and English invoices.

The plan limits the number of entities (entities.max); one more than the limit is entitlement_required. The slug is unique within the organization. Needs entities:write (organization owners and admins).

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: false · openWorldHint: false

Arguments

Argument	Type	Required	Description
`slug`	string	yes	(3–40 characters)
`legalName`	string	yes	(1–200 characters)
`tradingName`	string	no	(1–200 characters)
`establishment`	object	yes	–
`homeTaxId`	object	yes	–
`defaultCurrency`	string	yes	–
`timezone`	string	yes	–
`invoiceSettings`	object	no	–
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

validation_failed: A field is missing or malformed (details.issues).
slug_invalid: The slug has the wrong format or is a reserved word.
slug_taken: Another entity of this organization already uses this slug.
entitlement_required: The plan's entities.max is reached.
permission_denied: You can't create legal entities in this organization.

Example

A Croatian company

Arguments:

JSON

{
  "slug": "acme-hr",
  "legalName": "Acme Digital d.o.o.",
  "establishment": {
    "country": "HR",
    "address": {
      "line1": "Ilica 1",
      "city": "Zagreb",
      "postalCode": "10000"
    },
    "companyRegistryId": "080000000",
    "euVatEstablished": true
  },
  "homeTaxId": {
    "type": "eu_vat",
    "value": "HR12345678901"
  },
  "defaultCurrency": "EUR",
  "timezone": "Europe/Zagreb",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "object": "legal_entity",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "slug": "acme-hr",
  "legalName": "Acme Digital d.o.o.",
  "tradingName": null,
  "establishment": {
    "country": "HR",
    "subdivision": null,
    "address": {
      "line1": "Ilica 1",
      "line2": null,
      "city": "Zagreb",
      "postalCode": "10000",
      "region": null,
      "country": "HR"
    },
    "companyRegistryId": "080000000",
    "euVatEstablished": true
  },
  "homeTaxId": {
    "type": "eu_vat",
    "value": "HR12345678901"
  },
  "verification": {
    "status": "unverified",
    "method": "vies",
    "checkedAt": null
  },
  "defaultCurrency": "EUR",
  "timezone": "Europe/Zagreb",
  "invoiceSettings": {
    "numberFormat": "{series}-{year}-{seq:06}",
    "sequenceResetYearly": true,
    "language": "en",
    "bilingual": null,
    "footerText": null,
    "bankTransfer": null
  },
  "status": "onboarding",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}

`entities_get`

Get a legal entity. Operation entities.get · Organization level · permission entities:read · risk tier read · since M1

Returns one legal entity by its ID (ent_…): legal data, establishment, home tax ID and its verification, default currency, time zone and invoice settings. Entities outside the organization, or outside the entity of an entity-scoped request, are resource_not_found.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`ent_…`)	yes	–
`entity_id`	ID (`ent_…`)	no	Optional: act inside this legal entity (ent_…) instead of the whole organization.
`brand_id`	ID (`brd_…`)	no	Optional: act inside this brand (brd_…) instead of the whole organization.

Scope: the whole organization, or one legal entity or brand of it with entity_id or brand_id.
Read-only: changes nothing; idempotency_key is ignored.

Errors

resource_not_found: No entity with this ID is visible to the request.
permission_denied: You can't see legal entities here.

Example

Read an entity

Arguments:

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2"
}

Result output:

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "object": "legal_entity",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "slug": "acme-hr",
  "legalName": "Acme Digital d.o.o.",
  "tradingName": null,
  "establishment": {
    "country": "HR",
    "subdivision": null,
    "address": {
      "line1": "Ilica 1",
      "line2": null,
      "city": "Zagreb",
      "postalCode": "10000",
      "region": null,
      "country": "HR"
    },
    "companyRegistryId": "080000000",
    "euVatEstablished": true
  },
  "homeTaxId": {
    "type": "eu_vat",
    "value": "HR12345678901"
  },
  "verification": {
    "status": "unverified",
    "method": "vies",
    "checkedAt": null
  },
  "defaultCurrency": "EUR",
  "timezone": "Europe/Zagreb",
  "invoiceSettings": {
    "numberFormat": "{series}-{year}-{seq:06}",
    "sequenceResetYearly": true,
    "language": "en",
    "bilingual": null,
    "footerText": null,
    "bankTransfer": null
  },
  "status": "onboarding",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-13T12:00:00.000Z"
}

`entities_list`

List legal entities. Operation entities.list · Organization level · permission entities:read · risk tier read · since M1

Lists the organization's legal entities, newest first. An organization-level request sees every entity; a request inside one entity (an entity-scoped member, or an entity API key) sees only that entity. Paginate with limit (1–100, default 10) and starting_after (the next_cursor of the previous page).

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`limit`	integer	no	(1–100)
`starting_after`	ID (`ent_…`)	no	–
`entity_id`	ID (`ent_…`)	no	Optional: act inside this legal entity (ent_…) instead of the whole organization.
`brand_id`	ID (`brd_…`)	no	Optional: act inside this brand (brd_…) instead of the whole organization.

Scope: the whole organization, or one legal entity or brand of it with entity_id or brand_id.
Read-only: changes nothing; idempotency_key is ignored.

Errors

validation_failed: limit or starting_after is malformed.
permission_denied: You can't see legal entities here.

Examples

The first page

Arguments:

JSON

{
  "limit": 10
}

Result output:

JSON

{
  "object": "list",
  "data": [
    {
      "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
      "object": "legal_entity",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "slug": "acme-hr",
      "legalName": "Acme Digital d.o.o.",
      "tradingName": null,
      "establishment": {
        "country": "HR",
        "subdivision": null,
        "address": {
          "line1": "Ilica 1",
          "line2": null,
          "city": "Zagreb",
          "postalCode": "10000",
          "region": null,
          "country": "HR"
        },
        "companyRegistryId": "080000000",
        "euVatEstablished": true
      },
      "homeTaxId": {
        "type": "eu_vat",
        "value": "HR12345678901"
      },
      "verification": {
        "status": "unverified",
        "method": "vies",
        "checkedAt": null
      },
      "defaultCurrency": "EUR",
      "timezone": "Europe/Zagreb",
      "invoiceSettings": {
        "numberFormat": "{series}-{year}-{seq:06}",
        "sequenceResetYearly": true,
        "language": "en",
        "bilingual": null,
        "footerText": null,
        "bankTransfer": null
      },
      "status": "onboarding",
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

One per page

Arguments:

JSON

{
  "limit": 1
}

Result output:

JSON

{
  "object": "list",
  "data": [
    {
      "id": "ent_01m4tx5nj8emwbyf7y9vcf47x3",
      "object": "legal_entity",
      "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
      "slug": "acme-de",
      "legalName": "Acme GmbH",
      "tradingName": null,
      "establishment": {
        "country": "HR",
        "subdivision": null,
        "address": {
          "line1": "Ilica 1",
          "line2": null,
          "city": "Zagreb",
          "postalCode": "10000",
          "region": null,
          "country": "HR"
        },
        "companyRegistryId": "080000000",
        "euVatEstablished": true
      },
      "homeTaxId": {
        "type": "eu_vat",
        "value": "HR12345678901"
      },
      "verification": {
        "status": "unverified",
        "method": "vies",
        "checkedAt": null
      },
      "defaultCurrency": "EUR",
      "timezone": "Europe/Zagreb",
      "invoiceSettings": {
        "numberFormat": "{series}-{year}-{seq:06}",
        "sequenceResetYearly": true,
        "language": "en",
        "bilingual": null,
        "footerText": null,
        "bankTransfer": null
      },
      "status": "onboarding",
      "createdAt": "2026-10-13T12:00:00.000Z",
      "updatedAt": "2026-10-13T12:00:00.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "ent_01m4tx5nj8emwbyf7y9vcf47x3"
}

`entities_registry_extract_upload`

Upload a registry extract for verification. Operation entities.registry_extract.upload · Organization level · permission entities:tax_ids · risk tier write · since M12

Uploads the legal entity's extract from the company register (a PDF, PNG or JPEG of at most 10 MB) and asks Ownrecord to verify the entity from it: the verification becomes pending_review (method document) and the extract goes to Ownrecord's verification queue. You get the result by email, and the entity becomes verified (or rejected, with the reason) once it's reviewed.

Use it when the tax ID can't be checked with a public register (tax_id_check_not_available) or the register doesn't confirm it. Uploading again replaces the extract under review.

Needs entities:tax_ids (tax managers, owners and admins).

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`ent_…`)	yes	–
`content`	string	yes	The extract's bytes, base64-encoded: a PDF, PNG or JPEG file of at most 10 MB. (1–14081016 characters)
`filename`	string	no	(1–200 characters)
`entity_id`	ID (`ent_…`)	no	Optional: act inside this legal entity (ent_…) instead of the whole organization.
`brand_id`	ID (`brd_…`)	no	Optional: act inside this brand (brd_…) instead of the whole organization.
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Scope: the whole organization, or one legal entity or brand of it with entity_id or brand_id.
Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

registry_extract_invalid: The content isn't base64 of a PDF, PNG or JPEG file of at most 10 MB.
entity_already_verified: The entity is verified already.
upstream_timeout: The file store didn't answer in time; nothing was recorded. Retry.
resource_not_found: No such legal entity in your scope.
permission_denied: You can't verify this entity.

Example

Send a registry extract for review

Arguments:

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "content": "JVBERi0xLjQKJcOkw7zDtsOfCjEgMCBvYmoKPDwvVHlwZS9DYXRhbG9nPj4KZW5kb2JqCnRyYWlsZXIKPDwvUm9vdCAxIDAgUj4+CiUlRU9GCg==",
  "filename": "court-register-extract.pdf",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "entity": {
    "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
    "object": "legal_entity",
    "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
    "slug": "acme-hr",
    "legalName": "Acme Digital d.o.o.",
    "tradingName": null,
    "establishment": {
      "country": "HR",
      "subdivision": null,
      "address": {
        "line1": "Ilica 1",
        "line2": null,
        "city": "Zagreb",
        "postalCode": "10000",
        "region": null,
        "country": "HR"
      },
      "companyRegistryId": "080000000",
      "euVatEstablished": true
    },
    "homeTaxId": {
      "type": "eu_vat",
      "value": "HR12345678901"
    },
    "verification": {
      "status": "pending_review",
      "method": "document",
      "checkedAt": null
    },
    "defaultCurrency": "EUR",
    "timezone": "Europe/Zagreb",
    "invoiceSettings": {
      "numberFormat": "{series}-{year}-{seq:06}",
      "sequenceResetYearly": true,
      "language": "en",
      "bilingual": null,
      "footerText": null,
      "bankTransfer": null
    },
    "status": "onboarding",
    "createdAt": "2026-10-13T12:00:00.000Z",
    "updatedAt": "2026-10-13T12:00:00.000Z"
  },
  "verification": {
    "status": "pending_review",
    "method": "document",
    "checkedAt": null,
    "consultationNumber": null,
    "documentFileId": "file_01m4tx5nj8emwbyf7y9vcf47xe",
    "notes": null
  }
}

`entities_update`

Update a legal entity. Operation entities.update · Organization level · permission entities:write · risk tier write · since M1

Changes a legal entity's slug, legal and trading name, address, company registry ID, home tax ID, default currency, time zone or invoice settings (number format, language, footer, bank transfer details). Send only the fields to change; null removes an optional value.

The establishment country can't change: a company in another country is another legal entity. A new home tax ID resets the verification to unverified. Needs entities:write (organization owners and admins).

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: false

Arguments

Argument	Type	Required	Description
`id`	ID (`ent_…`)	yes	–
`slug`	string	no	(3–40 characters)
`legalName`	string	no	(1–200 characters)
`tradingName`	string or null	no	–
`establishment`	object	no	–
`homeTaxId`	object	no	–
`defaultCurrency`	string	no	–
`timezone`	string	no	–
`invoiceSettings`	object	no	–
`entity_id`	ID (`ent_…`)	no	Optional: act inside this legal entity (ent_…) instead of the whole organization.
`brand_id`	ID (`brd_…`)	no	Optional: act inside this brand (brd_…) instead of the whole organization.
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Scope: the whole organization, or one legal entity or brand of it with entity_id or brand_id.
Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

validation_failed: No field to change was sent, or one is malformed.
slug_invalid: The slug has the wrong format or is a reserved word.
slug_taken: Another entity of this organization already uses this slug.
resource_not_found: No entity with this ID is visible to the request.
version_conflict: The entity changed at the same time; retry.
permission_denied: You can't change legal entities here.

Example

Add bank transfer details for invoices

Arguments:

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "invoiceSettings": {
    "bankTransfer": {
      "iban": "HR1210010051863000160",
      "bic": "ZABAHR2X",
      "bankName": "Zagrebačka banka",
      "accountHolder": "Acme Digital d.o.o."
    }
  },
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "object": "legal_entity",
  "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
  "slug": "acme-hr",
  "legalName": "Acme Digital d.o.o.",
  "tradingName": null,
  "establishment": {
    "country": "HR",
    "subdivision": null,
    "address": {
      "line1": "Ilica 1",
      "line2": null,
      "city": "Zagreb",
      "postalCode": "10000",
      "region": null,
      "country": "HR"
    },
    "companyRegistryId": "080000000",
    "euVatEstablished": true
  },
  "homeTaxId": {
    "type": "eu_vat",
    "value": "HR12345678901"
  },
  "verification": {
    "status": "unverified",
    "method": "vies",
    "checkedAt": null
  },
  "defaultCurrency": "EUR",
  "timezone": "Europe/Zagreb",
  "invoiceSettings": {
    "numberFormat": "{series}-{year}-{seq:06}",
    "sequenceResetYearly": true,
    "language": "en",
    "bilingual": null,
    "footerText": null,
    "bankTransfer": {
      "iban": "HR1210010051863000160",
      "bic": "ZABAHR2X",
      "bankName": "Zagrebačka banka",
      "accountHolder": "Acme Digital d.o.o."
    }
  },
  "status": "onboarding",
  "createdAt": "2026-10-13T12:00:00.000Z",
  "updatedAt": "2026-10-14T09:30:00.000Z"
}

`entities_verify`

Verify a legal entity's tax ID. Operation entities.verify · Organization level · permission entities:tax_ids · risk tier write · since M12

Checks the legal entity's home tax ID with its public register and records the answer:

eu_vat with VIES (with the entity's own VAT ID as requester, so the answer carries a consultation number), gb_vat with HMRC and ch_vat with the Swiss UID register;
verified: the entity is verified (a brand of it may go live once the rest of the go-live checklist holds);
invalid: the register doesn't know the number; the entity stays unverified, with the reason in notes. Fix the tax ID (entities.update) or upload a registry extract (entities.registry_extract.upload);
unavailable: the register couldn't answer; nothing changes. Try again later.

Other tax ID types have no register to ask (tax_id_check_not_available): upload a registry extract instead. In development and CI the fixture registers answer (no real register is called).

Needs entities:tax_ids (tax managers, owners and admins).

Annotations: readOnlyHint: false · destructiveHint: false · idempotentHint: true · openWorldHint: true

Arguments

Argument	Type	Required	Description
`id`	ID (`ent_…`)	yes	–
`entity_id`	ID (`ent_…`)	no	Optional: act inside this legal entity (ent_…) instead of the whole organization.
`brand_id`	ID (`brd_…`)	no	Optional: act inside this brand (brd_…) instead of the whole organization.
`idempotency_key`	string	no	A unique string for this change. Retrying with the same key and arguments never acts twice. When left out, the server generates one and returns it in the result's `idempotency_key`. (1–255 characters)
`dry_run`	boolean	no	true: check permissions and rules and compute the result, then roll everything back. Nothing is saved. (default `false`)

Scope: the whole organization, or one legal entity or brand of it with entity_id or brand_id.
Idempotency: the result returns the idempotency_key used, yours or one the server generated. Retry with it: a call with the same key and arguments never acts twice (keys are kept for 24 hours).
Dry run: supported. dry_run: true checks permissions and rules and computes the result, then rolls everything back.

Errors

tax_id_check_not_available: The tax ID type has no register, or the number isn't well-formed.
entity_already_verified: The entity is verified already.
version_conflict: The entity changed while its tax ID was being checked; try again.
upstream_timeout: The register didn't answer in time (reported as unavailable).
resource_not_found: No such legal entity in your scope.
permission_denied: You can't verify this entity.

Example

VIES confirms the VAT ID

Arguments:

JSON

{
  "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
  "idempotency_key": "8d0c5f8e-4b7a-4e43-9b0f-2f6a0c1d9e21"
}

Result output:

JSON

{
  "entity": {
    "id": "ent_01m4tx5nj8emwbyf7y9vcf47x2",
    "object": "legal_entity",
    "orgId": "org_01m4tx5nj7ekd958x53w4bntcg",
    "slug": "acme-hr",
    "legalName": "Acme Digital d.o.o.",
    "tradingName": null,
    "establishment": {
      "country": "HR",
      "subdivision": null,
      "address": {
        "line1": "Ilica 1",
        "line2": null,
        "city": "Zagreb",
        "postalCode": "10000",
        "region": null,
        "country": "HR"
      },
      "companyRegistryId": "080000000",
      "euVatEstablished": true
    },
    "homeTaxId": {
      "type": "eu_vat",
      "value": "HR12345678901"
    },
    "verification": {
      "status": "verified",
      "method": "vies",
      "checkedAt": "2026-10-26T09:00:00.000Z"
    },
    "defaultCurrency": "EUR",
    "timezone": "Europe/Zagreb",
    "invoiceSettings": {
      "numberFormat": "{series}-{year}-{seq:06}",
      "sequenceResetYearly": true,
      "language": "en",
      "bilingual": null,
      "footerText": null,
      "bankTransfer": null
    },
    "status": "active",
    "createdAt": "2026-10-13T12:00:00.000Z",
    "updatedAt": "2026-10-13T12:00:00.000Z"
  },
  "verification": {
    "status": "verified",
    "method": "vies",
    "checkedAt": "2026-10-26T09:00:00.000Z",
    "consultationNumber": "WAPIAAAAZ1b2c3d4",
    "documentFileId": null,
    "notes": null
  },
  "check": {
    "outcome": "verified",
    "method": "vies",
    "consultationNumber": "WAPIAAAAZ1b2c3d4",
    "reason": null,
    "simulated": false
  }
}

entities_create#

Arguments#

Errors#

Example#

entities_get#

Arguments#

Errors#

Example#

entities_list#

Arguments#

Errors#

Examples#

entities_registry_extract_upload#

Arguments#

Errors#

Example#

entities_update#

Arguments#

Errors#

Example#

entities_verify#

Arguments#

Errors#

Example#

`entities_create`

Arguments

Errors

Example

`entities_get`

Arguments

Errors

Example

`entities_list`

Arguments

Errors

Examples

`entities_registry_extract_upload`

Arguments

Errors

Example

`entities_update`

Arguments

Errors

Example

`entities_verify`

Arguments

Errors

Example