Skip to content

Contacts & Directory

Manage your contact list, search the Peppol Directory to find participants, and import them with automatic Peppol registration verification.

GET/v1/contacts#

List all contacts for your account with optional filtering and pagination.

Query parameters

NameTypeRequiredDescription
namestringOptionalFilter by name (partial match)
isClientbooleanOptionalFilter clients only
isProviderbooleanOptionalFilter providers only
limitnumberOptionalMax results (default: 20)
offsetnumberOptionalPagination offset (default: 0)
import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

// List contacts with optional filters
const { data: contacts, meta } = await peppol.contacts.list({
  name: "Acme",        // filter by name (partial match)
  isClient: true,      // only clients
  limit: 10,
  offset: 0,
});

for (const contact of contacts) {
  console.log(`${contact.name} — ${contact.peppolId ?? "no Peppol ID"}`);
}

console.log(`Showing ${contacts.length} of ${meta.totalCount}`);
GET/v1/contacts/:id#

Retrieve a single contact by ID. Returns the full contact object including directoryVerified and directoryLastChecked fields.

Terminal
curl https://api.getpeppr.dev/v1/contacts/ac50912b-e9f8-4b4f-a7a6-30c8b42bdf5d \
  -H "Authorization: Bearer sk_sandbox_..."
POST/v1/contacts#

Create a new contact. If a peppolId is provided, getpeppr automatically verifies the participant against the Peppol Directory and populates enrichment fields.

Body parameters

NameTypeRequiredDescription
namestringRequiredContact name
peppolIdstringOptionalPeppol ID (e.g. 0208:0685660237) — triggers auto-enrichment
vatNumberstringOptionalVAT registration number
companyIdstringOptionalCompany registration number
streetstringOptionalStreet address
citystringOptionalCity
postalCodestringOptionalPostal / ZIP code
countrystringOptionalISO 3166-1 alpha-2 country code
emailstringOptionalContact email
phonestringOptionalPhone number
isClientbooleanOptionalMark as client (default: true)
isProviderbooleanOptionalMark as provider (default: false)
Include an Idempotency-Key header to safely retry requests without creating duplicate contacts. Send it blank — empty, or only whitespace — and the request is refused with 400 idempotency_key_blank: a key a transport reduces to an empty string cannot protect anything, so we say so rather than ignore it. That check runs after authentication and rate limiting, so a request that fails one of those receives that failure instead. If you do not need idempotency, omit the header rather than sending it empty.
import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

// Create a contact — if peppolId is provided, auto-enrichment kicks in
const contact = await peppol.contacts.create({
  name: "ACMEDIA",
  peppolId: "0208:0685660237",
  vatNumber: "BE0685660237",
  street: "Avenue Louise 54",
  city: "Brussels",
  postalCode: "1050",
  country: "BE",
  email: "invoices@wayne.be",
  isClient: true,
}, {
  // Retrying with the same key replays the first response rather than
  // creating a duplicate — and if that first call is still running, the
  // retry waits for it instead of racing it.
  idempotencyKey: "acmedia-import-2026-08",
});

console.log(`Created: ${contact.id}`);
// Read it back with contacts.get() to see directoryVerified / directoryLastChecked
PUT/v1/contacts/:id#

Update an existing contact. This is a partial update — only the fields you include in the request body are modified. Omitted fields remain unchanged.

import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

// Partial update — only provided fields are changed
const updated = await peppol.contacts.update("ac50912b-e9f8-4b4f-a7a6-30c8b42bdf5d", {
  email: "new-invoices@wayne.be",
  isProvider: true,
});

console.log(`Updated: ${updated.name}`);
DELETE/v1/contacts/:id#

Permanently delete a contact. Returns 204 No Content on success.

import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

await peppol.contacts.delete("ac50912b-e9f8-4b4f-a7a6-30c8b42bdf5d");
// Returns 204 No Content

Peppol Directory

The Peppol Directory is the public list of Peppol participants that publish a business card. Use it to find recipients before sending invoices. Publishing a business card is optional, so a participant can be registered on Peppol without being listed.

Search the Peppol Directory by name or VAT number, optionally narrowed by country. Country-only searches are accepted but usually exceed the Directory's accessible window.

Query parameters

NameTypeRequiredDescription
namestringOptionalSearch by name (min 3 characters)
countrystringOptionalOptional ISO 3166-1 alpha-2 filter; country-only searches are usually too broad
vatNumberstringOptionalVAT registration number
limitnumberOptionalMax participants per page (default: 20, max: 100)
offsetnumberOptionalZero-based participant offset (default: 0)
The name parameter requires a minimum of 3 characters. Directory search has its own bucket — 30 lookups per minute per key — to respect the public directory's usage policy. Pagination counts unique Peppol participants from one deduplicated collection. Subsequent page requests normally reuse that collection for up to one hour. If a query is wider than the public Directory's accessible 1,001-business-entity window, the API returns 400 directory.search_parameters_invalid; add or refine the business name or VAT number, using country only as a narrowing filter.
Directory results are live Peppol network participants — you can search and look them up from any environment, but sandbox delivers to one only if it is also registered on the Peppol test network; otherwise the send fails after submission. For test sends, use 9925:BE0314595348 (SPF Economie, the standard Peppol test receiver). See the sandbox guide. The reverse holds too: with a sandbox key, search and lookup still read this production directory, so a legal entity you register in the sandbox never appears in the results (see below).
import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

// Search the Peppol Directory by name, country, or VAT
const results = await peppol.directory.search({
  name: "ACMEDIA",       // min 3 characters
  country: "BE",       // ISO 3166-1 alpha-2
  limit: 5,
});

for (const entry of results.data) {
  console.log(`${entry.name} — ${entry.peppolId}`);
  console.log(`  Country: ${entry.country}, Registered: ${entry.registrationDate}`);
}
GET/v1/directory/:scheme/:id#

Look up a specific participant by their EAS scheme and identifier. Returns its Peppol Directory listing: name, capabilities, and metadata.

Write the identifier as /v1/directory/0208/0685660237 or /v1/directory/0208:0685660237; a symbolic scheme such as GB:VAT:123456789 works too. The form the Peppol Directory shows, iso6523-actorid-upis::0208:0685660237, is accepted as one segment: the prefix is removed before the lookup. An invoice's to.peppolId takes scheme:id only.

Use this to check whether a Peppol ID is listed before sending an invoice. A 404 does not prove the ID is inactive: see When a lookup answers 404.

On directory.participant_found, participant.registered: true means the identifier is listed in the Peppol Directory. If the directory is unavailable, the API falls back to our provider's registration check, in your key's environment, and answers directory.participant_found_via_provider with a thinner body; there, registered is the provider's answer.

import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

// Look up a specific participant by scheme:id
const result = await peppol.directory.lookup("0208:0685660237");

console.log(`Found: ${result.name}`);
console.log(`Capabilities: ${result.capabilities.join(", ")}`);

When a lookup answers 404

404 directory.participant_not_found means no participant was found: usually, that the identifier is not listed in the Peppol Directory, or, while the directory is unavailable, that our provider's check did not find it. It does not prove the identifier is unregistered on Peppol:

  • In production, a participant that has not published a business card is registered but unlisted. Sending to it can still work.
  • In the sandbox, the production directory never lists a legal entity you registered there: see Lookups with a sandbox key.

Lookups with a sandbox key

With a sandbox key, search and lookup still read the production Peppol Directory, while sandbox documents travel on the Peppol test network. The Getpeppr-Result-Message header is the same in both environments; a sandbox body adds a fixed note and a docs link to this section.

  • 200 directory.participant_found: the participant is listed in the production directory. It is reachable from the sandbox only if it is also registered on the test network, so send test documents to 9925:BE0314595348. The body adds note and docs next to participant, which is unchanged.
  • 200 directory.participant_found_via_provider: the directory was unavailable and our provider's sandbox check answered instead. The body is the provider's, with no note or docs.
  • 404: a legal entity registered in the sandbox is on the test network, which this lookup does not read while the production directory is available. Do not use the lookup to check a sandbox entity, and do not wait for it to appear. The body says so in error and adds docs.

To know whether one of your own identities is live, do not poll the directory. Read your account's identity with GET /v1/identity. Platform accounts can also read a legal entity with GET /v1/legal-entities/{id} or wait for the legal_entity.registered webhook.

Workflows

Import from Directory

A common workflow is to search the Peppol Directory, then import a participant as a contact. When you create a contact with a peppolId, auto-enrichment fills in any missing details from the directory.

Auto-enrichment only fills in fields you didn't provide. Your data always takes priority over directory data.
import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

// 1. Search the directory
const results = await peppol.directory.search({ name: "ACMEDIA", country: "BE" });
const match = results.data[0];

// 2. Import as a contact — auto-enrichment fills in the details
const contact = await peppol.contacts.create({
  name: match.name,
  peppolId: match.peppolId,
  country: match.country,
  isClient: true,
});

console.log(`Imported: ${contact.name} (${contact.peppolId})`);

Auto-Enrichment

When you create a contact with a peppolId, getpeppr automatically queries the Peppol Directory in the background and updates the contact with:

  • directoryVerified — true if the Peppol ID was found in the Peppol Directory at the last check (the production directory, with a sandbox key too). false does not prove the participant is unregistered: see When a lookup answers 404.
  • directoryLastChecked — timestamp of the last verification
  • Missing fields like name, country, and vatNumber (if not provided by you)
The create call waits for the directory lookup before answering, but the object it returns is the row as you sent it — read the contact back with GET to see directoryVerified and directoryLastChecked. Enrichment never overwrites fields you explicitly provided.

Re-verify a Contact

To check if a contact is still listed in the Peppol Directory, use the directory lookup endpoint with their Peppol ID. This is useful for periodic validation of your contact list.

import { Peppol } from "@getpeppr/sdk";

const peppol = new Peppol({ apiKey: "sk_sandbox_..." });

// Check if a contact is still registered on Peppol
const contact = await peppol.contacts.get("ac50912b-e9f8-4b4f-a7a6-30c8b42bdf5d");

try {
  await peppol.directory.lookup(contact.peppolId as `${string}:${string}`);
  console.log(`${contact.name} is still active on Peppol`);
} catch {
  console.warn(`${contact.name} is no longer registered!`);
}