Skip to main content

Onboard a Legal Entity

warning

Documentation is released in preview, is not final, and may be subject to changes. Sandbox and Production environments will be available soon.

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
pendingA Legal Entity has been added to the A-Cube Platform, but still needs to be validated.
waiting_user_interactionA Legal Entity started the connection process with A-Cube on the Finančná správa portal but hasn't completed it yet.
waiting_user_interaction_after_failA Legal Entity failed the connection process with A-Cube on the Finančná správa portal, but can try again.
activeLegal Entity has been successfully onboarded.
blockedLegal Entity has been blocked due to an incorrect onboarding process or set manually by the administrator.

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 pending, waiting_user_interaction or waiting_user_interaction_after_fail 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 supplierInvoiceEnabled 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 pending and the onboarding_url will be returned.

{
  "uuid": "01a047df-a310-75f9-8176-b9370c82a850",
  "taxId": "5555444444",
  "ico": "55555349",
  "icDph": "SK5555444444",
  "status": "pending",
  "name": "A-Cube Test Company",
  "email": "test@acme.test",
  "phoneNumber": "+421900000000",
  "country": "SK",
  "address": "Staromestská 123",
  "city": "Bratislava",
  "stateOrProvince": null,
  "zipCode": "811 06",
  "finalizeOnboardingUrl": "/initiate-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 active 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/initiate-onboarding/01a047df-a310-75f9-8176-b9370c82a850

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

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 active 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 waiting_user_interaction_after_fail 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 active.

Errors and retries​

If the Legal Entity is not in active or blocked 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