Sub-tenant lifecycle

How each customer moves from created to live on Peppol — every status, and what sandbox and production each require.

The customer journey

Every customer you onboard moves through the same managed pipeline. You drive it with a few API calls; getpeppr runs the regulated steps in between.

1. Create — POST /v1/legal-entities with the customer's company details and Peppol identifier. We validate the format and start registry verification.
2. Verify — we check the identifier against the country's business registry and match the declared company name. (verifying → verified)
3. Authorise (production) — request an attestation; the customer confirms, on a getpeppr-signed page, that they authorise invoicing on their behalf. (awaiting_authz → attested)
4. Provision — we register the verified, authorised identity on the Peppol network. (provisioning → active)
5. Live — the customer can send and receive. You're notified at each step by webhook.

Read a customer's status any time with GET /v1/legal-entities/:id — or let the lifecycle webhooks push each transition to you, no polling required.

Check a customer's status

curl https://api.getpeppr.dev/v1/legal-entities/7c9a1b34-2d5e-4f60-8a1b-9c2d3e4f5a6b \
  -H "Authorization: Bearer sk_live_your_master_key"

Response

{
  "id": "7c9a1b34-2d5e-4f60-8a1b-9c2d3e4f5a6b",
  "externalId": "customer_8412",
  "companyName": "Bright Health Ltd",
  "country": "GB",
  "identifier": { "scheme": "GB:CRN", "value": "12345678" },
  "status": "awaiting_authz",
  "environment": "production",
  "createdAt": "2026-06-01T10:00:00.000Z"
}

Status reference

The status field on a customer tells you exactly where they are in the pipeline. These five apply in every environment:

Sub-tenant status values in every environment
Status	Meaning
`pending`	Created; verification queued or not yet conclusive.
`verifying`	Being checked against the country's business registry.
`verified`	Identity confirmed. In sandbox, the customer is ready to invoice.
`verification_failed`	Registry name mismatch or identifier not found.
`archived`	Off-boarded. No longer listed and cannot send.

Production adds an authorisation stage

On production, a verified customer must be authorised and registered on the live network before going active. These statuses layer on top:

Additional production status values
Status	Meaning
`awaiting_authz`	Attestation requested; waiting for the customer to confirm.
`expired`	The attestation request lapsed before the customer confirmed.
`attested`	Customer authorised. Network registration will begin.
`provisioning`	Being registered on the Peppol network.
`active`	Live on Peppol. Ready to send and receive.
`provisioning_failed`	Network registration failed and will be retried.

Sandbox vs production

The pipeline has the same shape everywhere, but production adds the steps that make an identity legally real on the network.

Sandbox — a customer is auto-activated once verified. No attestation step. Build and test your whole integration end-to-end before any agreement.
Production — a customer must be verified and authorised (attestation) before getpeppr registers them on the live Peppol network.

Attestation is a production-only concept. Calling the attestation endpoint with a sandbox key returns 400 — sandbox customers are already active once verified.

Outcomes and terminal states

Two states need action; one is an intentional end state.

verification_failed — the registry returned a name mismatch or didn't find the identifier. The response carries a verificationDetail.reason of name_mismatch or not_found. The customer can't go live until it's resolved.
expired — an attestation request wasn't completed before it expired (see expiresAt on the attestation response). Request a new one to resend the email.
archived — intentional: you off-boarded the customer with a DELETE. They drop out of lists and can no longer send.

Network identifiers and VAT

When getpeppr registers a customer on the Peppol network, it attaches the identifier you declared at creation — and, where VAT registration can be proven, the matching VAT identifier as well. For Belgian customers (0208), the BE:VAT identifier is derived from the enterprise number and registered automatically. For Swedish customers (0007), the SE:VAT identifier is derived from the organisation number; because the Swedish company registry does not prove VAT registration (momsregistrering), getpeppr first confirms the derived VAT number against VIES (the EU VAT registry) before publishing it in production. In both cases there is nothing extra to send in your payload.

The VAT identifier matters at send time: a Peppol invoice that carries VAT — including 0% rates and tax-exempt invoices — is rejected when the sending identity has no registered VAT number.

If a send returns 422 with "The sub-tenant Legal Entity selected by 'sender' has no VAT identifier registered", the customer's entity predates automatic VAT registration or its verification could not prove VAT registration. Contact support — verified entities can be backfilled without re-onboarding.

Platform Overview

Legal Entities API