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.

Platform Overview

Legal Entities API