POST/v1/exports

Request a data export

Items or the suppression list as CSV, templates as a zip with JSON documents and assets; poll until READY, then download within 24 hours (PRIV-003).

Scope organisation.settingsIdempotent with a keyRate limit class export

Headers

Idempotency-Keystringmax length 255

Up to 255 characters, scoped to the organisation and the endpoint, kept for 24 hours: a repeat with the same body replays the stored response with Idempotent-Replayed: true (API-004).

Body

kindenumrequired

itemssuppressionstemplates

Returns

11 fields of the 202 answer

idstringrequired

kindenumrequired

itemssuppressionstemplates

statusenumrequired

PENDINGRUNNINGREADYFAILEDEXPIRED

fileNamestringrequired

contentTypestringrequired

countsobjectrequired

errorstring or nullrequired

downloadUrlstring or nullrequired

expiresAtdate-time or nullrequired

createdAtdate-timerequired

finishedAtdate-time or nullrequired

Responses

202Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

409A request with this Idempotency-Key is still in progress (idempotency_in_progress)

422Validation failed

429Rate limited for this API key and class; wait Retry-After seconds

otherError (RFC 9457 problem details)

curl -X POST https://api.postbuddy.nl/v1/exports \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Idempotency-Key: crm-0062p00001Xyz-signed" \ -H "Content-Type: application/json" \ -d '{ "kind": "items" }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.exports.request({ body: { kind: 'items', },, idempotencyKey: 'crm-0062p00001Xyz-signed', });

{ "id": "exp_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "kind": "items", "status": "READY", "fileName": "customers.csv", "contentType": "Example", "counts": { "key": 1 }, "error": "Example", "downloadUrl": "https://example.com/r/Fq3ZtR8w", "expiresAt": "2026-10-16T09:14:02.000Z", "createdAt": "2026-10-16T09:14:02.000Z", "finishedAt": "2026-10-16T09:14:02.000Z" }

{ "type": "https://docs.postbuddy.nl/errors/idempotency_in_progress", "title": "Request with this idempotency key in progress", "status": 409, "code": "idempotency_in_progress", "detail": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K" }

{ "type": "https://docs.postbuddy.nl/errors/validation_failed", "title": "Validation failed", "status": 422, "code": "validation_failed", "detail": "Validation failed", "requestId": "req_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "errors": [ { "field": "recipient.postalCode", "code": "invalid_string", "message": "Invalid postal code" } ] }