Skip to main content
Download OpenAPI

Onboard a Legal Entity

To register a new Legal Entity, you need to send properly formatted JSON, as defined in this endpoint.

note

Every Legal Entity must have a unique VAT number (DIČ), and a unique IČO and IČ DPH (if available) in A-Cube. The same Legal Entity cannot be registered twice in two different accounts.

Every Legal Entity has a marking property that describes its onboarding status and whether it can operate in the system.

StatusDescription
TO_BE_ONBOARDEDA Legal Entity has been added to the A-Cube Platform, but still needs to be validated.
ONBOARDING_STARTEDA Legal Entity started the connection process with A-Cube on the Finančná správa portal but hasn't completed it yet.
ONBOARDING_FAILEDA Legal Entity failed the connection process with A-Cube on the Finančná správa portal, but can try again.
ONBOARDEDLegal Entity has been successfully onboarded.

A-Cube platform will help you to start your onboarding process for sending and receiving documents to and from other entities, but your interaction is needed to complete the registration process on the Finančná správa portal: you can do that when a Legal Entity is in a TO_BE_ONBOARDED, ONBOARDING_STARTED or ONBOARDING_FAILED status.

Onboarding steps​

note

The following steps refer to the onboarding process for the production environment. If you want to try our API, you can register a Legal Entity for testing purposes in the Sandbox environment. Please refer to the Quick Start for Sandbox page.

Register a Legal Entity in A-Cube by using the POST /legal-entities endpoint.

{
  "taxId": "5555444444",
  "ico" : "55555349",
  "icDph": "SK5555444444",
  "name": "A-Cube Test Company",
  "email": "test@acme.test",
  "phoneNumber": "+421900000000",
  "country": "SK",
  "address": "Staromestská 123",
  "city": "Bratislava",
  "zipCode": "811 06",
  "config": {
    "supplierInvoiceEnabled": true,
    "customerInvoiceEnabled": true
  }
}
note

A Legal Entity can enable outgoing invoice submission with customerInvoiceEnabled parameter only if both IČO and IČ DPH are registered in A-Cube.

A-Cube will check if the provided taxId (DIČ), IČO and IČ DPH are in an expected format and unique in A-Cube.

If all the checks are successful, the Legal Entity will be registered in A-Cube with status TO_BE_ONBOARDED and the onboarding_url will be returned.

{
  "uuid": "01a047df-a310-75f9-8176-b9370c82a850",
  "taxId": "5555444444",
  "ico": "55555349",
  "icDph": "SK5555444444",
  "status": "TO_BE_ONBOARDED",
  "name": "A-Cube Test Company",
  "email": "test@acme.test",
  "phoneNumber": "+421900000000",
  "country": "SK",
  "address": "Staromestská 123",
  "city": "Bratislava",
  "stateOrProvince": null,
  "zipCode": "811 06",
  "finalizeOnboardingUrl": "https://sk.api.acubeapi.com/finalize-onboarding/01a047df-a310-75f9-8176-b9370c82a850",
  "createdAt": "2026-08-28T10:17:13+00:00",
  "updatedAt": "2026-08-28T10:17:13+00:00",
  "config": {
    "supplierInvoiceEnabled": true,
    "customerInvoiceEnabled": true
  }
}

The Legal Entity is not already set in status ONBOARDED because a legal entity representative must complete the onboarding process in the Finančná Správa's Aplikácia pre výber certifikovaného poskytovateľa doručovacej služby (VPDS) portal.

Open the finalizeOnboardingUrl in a web browser. You will be redirected automatically to the A-Cube provider selection in the VPDS portal.

Referring to the example above, the url will be:

https://sk.api.acubeapi.com/finalize-onboarding/01a047df-a310-75f9-8176-b9370c82a850

The status of the Legal Entity in A-Cube will be updated to ONBOARDING_STARTED.

Please complete the process in the VPDS portal by logging in with the Legal Entity representative Slovak digital credentials and follow the instructions.

If the Legal Entity representative completes the onboarding process successfully, the Legal Entity will be marked as ONBOARDED in A-Cube. The Legal Entity will be registered by A-Cube in the Peppol Network with all the Billing and Self-Billing invoice and credit note capabilities.

If the onboarding process fails, the Legal Entity will be marked as ONBOARDING_FAILED and can try to finalize the onboarding process again in the VPDS portal.

3. After onboarding​

Read the entity with GET /legal-entities/{legalEntityId} and confirm that status is ONBOARDED.

Errors and retries​

If the Legal Entity is not in ONBOARDED status, the onboarding process can be retried by following steps 2 and 3.

Environments​

To read more about specific features and limitations in particular environments, please read:

Last updated on