Legal Entities API

Provision, list, authorise, and off-board your customers as Peppol legal entities. The multi-tenant surface for platforms.

Every endpoint here requires a master key with the matching legal_entities:* scope. A standard key receives 403. Customers you don't own return 404, never another platform's data.

POST /v1/legal-entities #

Create a customer as a draft Peppol legal entity. getpeppr validates the identifier format (for example, a Luhn check), then kicks off registry verification asynchronously. Returns 202 on creation, or 200 if the same externalId is replayed (the call is idempotent).

Body parameters

Name	Type	Required	Description
`externalId`	string	Required	Your stable reference for this customer (1–64 chars). Echoed on every response and webhook.
`companyName`	string	Required	Legal company name (2–64 chars). Matched against the business registry.
`country`	string	Required	ISO 3166-1 alpha-2 country code (e.g. GB).
`address.line1`	string	Required	Street address (2–192 chars).
`address.city`	string	Required	City (2–64 chars).
`address.zip`	string	Required	Postal / ZIP code (2–32 chars).
`identifier.scheme`	string	Required	Peppol identifier scheme (1–16 chars, e.g. GB:CRN, 0208).
`identifier.value`	string	Required	The identifier value (1–64 chars). Format-checked (e.g. Luhn) before verification.

Terminal

curl https://api.getpeppr.dev/v1/legal-entities \
  -H "Authorization: Bearer sk_live_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "customer_8412",
    "companyName": "Bright Health Ltd",
    "country": "GB",
    "address": { "line1": "10 King Street", "city": "London", "zip": "EC2V 8EA" },
    "identifier": { "scheme": "GB:CRN", "value": "12345678" }
  }'

Response

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

GET /v1/legal-entities #

List the customers you manage, newest first. Results are isolated to your platform account. When offset exceeds the total, data is empty and has_more is false.

Query parameters

Name	Type	Required	Description
`limit`	number	Optional	Max results (default 50, max 100).
`offset`	number	Optional	Pagination offset (default 0, max 100000).

Terminal

curl "https://api.getpeppr.dev/v1/legal-entities?limit=20&offset=0" \
  -H "Authorization: Bearer sk_live_your_master_key"

Response

{
  "data": [
    {
      "id": "7c9a1b34-2d5e-4f60-8a1b-9c2d3e4f5a6b",
      "externalId": "customer_8412",
      "companyName": "Bright Health Ltd",
      "country": "GB",
      "identifier": { "scheme": "GB:CRN", "value": "12345678" },
      "status": "active",
      "environment": "production",
      "createdAt": "2026-06-01T10:00:00.000Z"
    }
  ],
  "pagination": { "total_count": 42, "offset": 0, "limit": 20, "has_more": true }
}

GET /v1/legal-entities/:id #

Retrieve a single customer by their getpeppr id. On production this surfaces the full attestation lifecycle status (see the status reference); in sandbox it returns the verification status. Unknown or unowned ids return 404.

DELETE /v1/legal-entities/:id #

Off-board a customer. The legal entity is archived (soft-deleted) and can no longer send. Returns 200 with the archived entity.

Response

{
  "id": "7c9a1b34-2d5e-4f60-8a1b-9c2d3e4f5a6b",
  "externalId": "customer_8412",
  "status": "archived"
}

POST /v1/legal-entities/:id/attestation #

Request (or resend) the customer's authorisation. getpeppr emails a co-branded, getpeppr-signed attestation link to the contact; once they confirm, the customer advances toward active. Production only — calling this with a sandbox key returns 400.

Body parameters

Name	Type	Required	Description
`contactEmail`	string	Required	Email of the person who will authorise invoicing for this customer (max 254 chars).
`contactName`	string	Optional	Display name shown in the authorisation email (max 128 chars).

Returns 409 if the customer isn't verified yet or has already attested, and 502 if the email couldn't be sent (retry to mint a fresh link). Issuing an attestation emits a legal_entity.awaiting_authz webhook.

Terminal

curl https://api.getpeppr.dev/v1/legal-entities/7c9a1b34-2d5e-4f60-8a1b-9c2d3e4f5a6b/attestation \
  -H "Authorization: Bearer sk_live_your_master_key" \
  -H "Content-Type: application/json" \
  -d '{
    "contactEmail": "owner@brighthealth.co.uk",
    "contactName": "Dr Jane Okafor"
  }'

Response

// 202 Accepted — co-branded email sent to the customer
{
  "id": "7c9a1b34-2d5e-4f60-8a1b-9c2d3e4f5a6b",
  "externalId": "customer_8412",
  "status": "awaiting_authz",
  "expiresAt": "2026-06-08T10:00:00.000Z"
}

Sub-tenant Lifecycle

Sending & Webhooks