Sub-tenant lifecycle

Each supported customer you onboard moves through the same API lifecycle. You drive it with a few API calls; getpeppr runs the regulated steps in between.

1. 1. Create — POST /v1/legal-entities with the customer's company details and Peppol identifier. We validate the format and start registry verification.
2. 2. Verify — where automatic verification is available, we check the identifier with the relevant verification source and match the declared company name when that source returns one. (verifying → verified)
3. 3. Authorise (production) — request an attestation; the customer confirms, on a getpeppr-signed page, that they authorise you to register them on the Peppol network and to send and receive their electronic invoices. (awaiting_authz → attested)
4. 4. Publish — we attach the verified identity at Storecove. This is the provider-local registration used by the existing outbound send gate; it is not proof that another Access Point can find the customer.
5. 5. Discover — from the official SML record, we follow the advertised SMP and require the exact participant, Invoice BIS Billing 3.0 metadata, and an active AS4 v2 endpoint with a current, non-revoked OpenPeppol G3 certificate. (provisioning)
6. 6. Receive-ready — only that public cross-Access-Point proof changes the customer to active and emits legal_entity.registered.

The status field on a customer tells you exactly where they are in the pipeline. These six apply in every environment, plus two that only the sandbox produces:

Authorisation and receive readiness

Production alone adds the authorisation states. Storecove publication and public cross-Access-Point discovery can surface provisioning and active in both environments. These statuses layer on top:

Receive discovery detail

Every Legal Entity response includes networkDiscovery. It reports the receive-only check without exposing SMP URLs, DNS answers, XML, or another copy of the participant ID. Verified entries are checked again every 24 hours so later certificate expiry, revocation, or publication loss cannot stay marked receive-ready indefinitely.

• state — pending, verified, or failed. A failed check remains on a slower automatic retry schedule.
• attempts — consecutive public discovery attempts started since the latest success; it resets to 0 whenever discovery verifies the customer.
• checkedAt — when the latest attempt finished, when available.
• nextAttemptAt — when another automatic attempt is due, when available.
• error — a bounded machine-readable reason on failed; no raw network response is returned.

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

• Sandbox — no attestation step. After identity verification, getpeppr publishes on the test network and checks public discovery there. Identity verified alone is not receive-ready.
• Production — a customer must be verified and authorised (attestation) before Storecove publication; getpeppr then proves the public live-network discovery path before returning active.

Three 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. A not_found has more than one cause, and verificationDetail.registryStatus helps tell them apart: when it reads inactive, the registry does know the company but doesn't consider it active — struck off, in liquidation, or not yet active. Re-sending the same details won't change the answer until the registry itself changes it, so the customer generally has to supply a company that is trading today. When the field is absent, all it means is that we have no such finding to show — never that none exists, and never that the company is unknown. The registry may have no entry, may have been unreachable, our team may have reviewed an earlier finding, or there may simply be no inactive finding on record — a valid VAT registration can verify a company on its own, so the national registry isn't always consulted, and isn't always what settles the answer. So check at the customer's own national registry that the company is trading before you go looking for a typo, and treat this field as a positive signal only.
• unsupported_scheme — automatic verification is unavailable for this identifier scheme. This is terminal for your current request, not a failed registry check and not a reason to keep polling. Contact support before sending. The internal row remains resumable if support for the scheme is added later.
• registration_failed — identity verification succeeded, but sandbox network registration did not. Read registrationDetail.reason on GET or LIST: already_registered, invalid_format, or provider_error. This diagnostic is stable and deliberately coarse; raw provider errors stay private.
• 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.

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. For Norwegian customers (0192), the MVA number (NO:VAT) is added only after the Norwegian business register confirms, at registration time, that the company is in the VAT Register; it is never announced as a Peppol address (see Norwegian customers). In every case 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.

getpeppr checks VAT registration when it registers the identifier, not afterwards. If a customer's VAT registration ends — in any country — acting on it is yours: in sandbox, archive the legal entity and create it again; in production, contact support. The accuracy and legality of the invoices your customers send remain theirs and yours (Terms §5).