Skip to main content
Download OpenAPI

Onboarding Legal Entity

Onboarding is the only way to bring a UAE taxpayer into A-Cube: a legal entity cannot be created with a "create request", it is always the result of a flow started by the taxpayer in EmaraTax.

The passport​

The API enforces the order of the four steps with a short-lived, signed JWT called the passport: every step returns one in the passport field, and you send it back on the next call in the X-Onboarding-Passport header.

  • One per step. Always send the value returned by the immediately preceding call, not an earlier one.
  • Each one unlocks only the next endpoint. This prevents out-of-order calls and keeps partial states out of the database.
  • It expires. The window to complete the chain after the EmaraTax handoff is five minutes, in the sandbox as in production.

LINK onboards a new taxpayer, from the EmaraTax handoff to an active legal entity.

Before the first call: the handoff​

Your integration starts when EmaraTax redirects the taxpayer to your landing page, with an authorization code in the URL.

If you want to test the onboarding flow on sandbox, please read our Quick Start.

1. Verification​

POST /legal-entities/onboarding/verify is the entry point, and the only step with a body and no passport.

{
  "token": "<authCode from the EmaraTax redirect>",
  "tin": "1069086623",
  "email": "admin@mail.com",
  "action": "LINK"
}

A-Cube validates the code and the TIN against EmaraTax and returns the verified company data with the first passport. Nothing is persisted yet: this step only proves that the taxpayer really did appoint you.

{
  "action": "LINK",
  "step": "INITIALIZATION",
  "isCompleted": false,
  "legalEntity": {
    "tin": "1069086623",
    "nameEn": "ACube Global Technologies LLC",
    "vatTrn": "100654190600003",
    "email": "admin@mail.com",
    "legalEntityId": null
  },
  "passport": "<verification_passport>"
}

step is the step you must call next, and legalEntityId stays null until initialization creates the resource.

2. Initialization​

POST /legal-entities/onboarding/init, with the passport from step 1 and no body. It consolidates the verified data and creates the legal entity, so this is where legalEntityId first appears. Store it: it identifies the entity in every later call.

It also sanitises abandoned sessions. If a previous attempt stopped halfway — say the Peppol registration succeeded but the central registry sync did not — A-Cube detects the orphaned state here and cleans it up before restarting. You do not need to handle that yourself.

3. SMP Sync​

POST /legal-entities/onboarding/sync-smp publishes the entity's receiving capabilities to the Peppol SMP, which is what makes it addressable on the network. Until this succeeds the entity cannot receive anything.

4. Central Registry Sync​

POST /legal-entities/onboarding/sync-central-registry seals the registration with the government central registry and returns 204 No Content. There is no final payload: the status code is the completion signal, and the taxpayer now sees the result in EmaraTax.

After onboarding​

Read the entity with GET /legal-entities/{legalEntityId} and confirm that status is Active. The response also lists enabledCapabilities, the Peppol document types the entity can receive.

Errors and retries​

  • A step fails. Retry it with the same passport, while it is still valid. Passports are bound to a specific next endpoint, so a retry cannot skip ahead.
  • The passport expired. Start again from verification. In production this needs a fresh handoff from EmaraTax, because the authorization code is single-use.

Onboarding emits the legal_entity.synchronized webhook as synchronization steps complete. See Event Types to drive the flow asynchronously instead of waiting on the responses.

Environments​

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

Last updated on