Contacts & Directory
Manage your contact list, search the Peppol Directory to find participants, and import them with automatic Peppol registration verification.
List all contacts for your account with optional filtering and pagination.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Optional | Filter by name (partial match) |
isClient | boolean | Optional | Filter clients only |
isProvider | boolean | Optional | Filter providers only |
limit | number | Optional | Max results (default: 20) |
offset | number | Optional | Pagination 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}`);Retrieve a single contact by ID. Returns the full contact object including directoryVerified and directoryLastChecked fields.
curl https://api.getpeppr.dev/v1/contacts/ac50912b-e9f8-4b4f-a7a6-30c8b42bdf5d \
-H "Authorization: Bearer sk_sandbox_..."Create a new contact. If a peppolId is provided, getpeppr automatically verifies the participant against the Peppol Directory and populates enrichment fields.
Body parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Required | Contact name |
peppolId | string | Optional | Peppol ID (e.g. 0208:0685660237) — triggers auto-enrichment |
vatNumber | string | Optional | VAT registration number |
companyId | string | Optional | Company registration number |
street | string | Optional | Street address |
city | string | Optional | City |
postalCode | string | Optional | Postal / ZIP code |
country | string | Optional | ISO 3166-1 alpha-2 country code |
email | string | Optional | Contact email |
phone | string | Optional | Phone number |
isClient | boolean | Optional | Mark as client (default: true) |
isProvider | boolean | Optional | Mark as provider (default: false) |
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 / directoryLastCheckedUpdate 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}`);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 ContentPeppol 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
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Optional | Search by name (min 3 characters) |
country | string | Optional | Optional ISO 3166-1 alpha-2 filter; country-only searches are usually too broad |
vatNumber | string | Optional | VAT registration number |
limit | number | Optional | Max participants per page (default: 20, max: 100) |
offset | number | Optional | Zero-based participant offset (default: 0) |
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.
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}`);
}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 to9925:BE0314595348. The body addsnoteanddocsnext toparticipant, 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 nonoteordocs. - 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
errorand addsdocs.
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.
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—trueif the Peppol ID was found in the Peppol Directory at the last check (the production directory, with a sandbox key too).falsedoes not prove the participant is unregistered: see When a lookup answers 404.directoryLastChecked— timestamp of the last verification- Missing fields like
name,country, andvatNumber(if not provided by you)
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!`);
}