Skip to content

REST API · v1

API documentation

Let your own software send brochures. Your system places an order; we print and fold the brochure and send it by post. Everything runs as JSON over HTTPS.

Quick start

  1. Log in and go to “Integraties” → “API-sleutels” (Integrations → API keys). You need the “Integraties” (Integrations) team permission for this.
  2. Create a key with a name, the scopes your integration needs and a validity period. Copy the key straight away: you will only see it once.
  3. Put the key in an environment variable and retrieve your brochures:
curl https://slimfolderen.nl/api/v1/brochures?status=active \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"

Base URL: https://slimfolderen.nl/api/v1. Send Accept: application/json with every request, so that errors are returned as JSON as well.

Authentication and scopes

Send the key as a bearer token: Authorization: Bearer 12|Xh3k…. A key acts on behalf of the colleague who created it. Orders are placed in their name and follow their permissions. A key created by an administrator sees all of the company’s orders; keys of other roles see only their own orders.

A key can only call the endpoints it has a scope for:

ScopeGives access to
orders:create“Orders plaatsen” (place orders). Place orders (individually or in a batch) and calculate the cost in advance. Uses credit.
orders:read“Orders inzien” (view orders). Retrieve orders and their shipping status.
brochures:read“Brochures inzien” (view brochures). Retrieve brochures, for example to pick the right brochure_id.
campaigns:read“Campagnes inzien” (view campaigns). Retrieve webhook campaigns. The webhook URL and token stay hidden.
documents:upload“Documenten uploaden” (upload documents). Upload a PDF (with a security scan) and turn it into a brochure or letter.
letters:read“Brieven inzien” (view letters). Retrieve letters, their fields and a preview.
letters:write“Brieven beheren” (manage letters). Create, change and archive letters.

Your credit balance, team, settings, other API keys and payments can never be reached with an API key, not even with all scopes. Choose a validity period for each key, from 30 days to one year, or let it never expire. Revoke a key as soon as you stop using it; the portal shows when each key was last used.

Endpoints

  • GET/brochures

    Brochures, newest first. Filters: status, format, search.

    Scope: brochures:read

  • GET/brochures/{id}

    A single brochure.

    Scope: brochures:read

  • POST/documents/upload-url

    Start uploading a PDF: returns an upload_token and the upload_url.

    Scope: documents:upload

  • GET/documents/upload-status/{token}

    Status of the upload and the scan. Poll until passed.

    Scope: documents:upload

  • POST/brochures

    Create a brochure from an approved upload.

    Scope: documents:upload

  • GET/letters/settings

    Whether attaching letters is enabled, the price per sheet, typefaces and standard fields.

    Scope: letters:read

  • GET/letters

    Letters, newest first. Filter: status (active or archived).

    Scope: letters:read

  • POST/letters

    Create a letter: text with fields, or your own PDF.

    Scope: letters:write

  • POST/letters/preview

    Preview PDF of a text letter that has not been saved yet.

    Scope: letters:read

  • GET/letters/{id}

    A single letter, with the fields it uses.

    Scope: letters:read

  • PATCH/letters/{id}

    Change or archive a letter.

    Scope: letters:write

  • DELETE/letters/{id}

    Delete a letter. Orders already placed keep their letter.

    Scope: letters:write

  • GET/letters/{id}/pdf

    Preview PDF of a saved letter.

    Scope: letters:read

  • POST/orders/estimate

    Calculate the cost without sending anything.

    Scope: orders:create

  • POST/orders

    Place one order (or a bulk order to one address).

    Scope: orders:create

  • POST/orders/batch

    The same brochure to up to 100 recipients.

    Scope: orders:create

  • POST/onepagers/estimate

    Calculate the cost of a one-pager without sending anything.

    Scope: orders:create

  • POST/onepagers

    Send a letter on its own as a one-pager: one A4 sheet, no booklet.

    Scope: orders:create

  • POST/onepagers/batch

    The same one-pager to up to 100 recipients.

    Scope: orders:create

  • GET/orders

    Orders, newest first. Filters: status, source, kind, brochure_id, external_reference, date_from, date_to.

    Scope: orders:read

  • GET/orders/{id}

    A single order with its status history.

    Scope: orders:read

  • GET/orders/{id}/letter

    The letter PDF as it goes with this order.

    Scope: orders:read

  • GET/orders/saved

    Saved orders per brochure: how many addresses are waiting and when the first leaves at the latest.

    Scope: orders:read

  • POST/orders/{id}/send-now

    Send a saved order now, without batch discount.

    Scope: orders:create

  • POST/orders/{id}/cancel-saved

    Cancel a saved order; the credit is returned.

    Scope: orders:create

  • GET/campaigns

    Webhook campaigns. Filter: active.

    Scope: campaigns:read

  • GET/campaigns/{id}

    A single campaign.

    Scope: campaigns:read

Lists are paginated: the items are in data, with current_page, last_page and total alongside. Use page and per_page (up to 100).

Placing and tracking orders

An order costs credits from your wallet: printing costs per page plus shipping costs per address. Calculate the cost first if you want to show or check it:

Calculate the cost
curl -X POST https://slimfolderen.nl/api/v1/orders/estimate \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"brochure_id": "9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34", "recipient_country": "NL"}'
Response
{
  "print_credits": 10,
  "shipping_credits": 12,
  "total_credits": 22,
  "paper": { "key": "normal", "label": "Standaard", "cover_gsm": 120, "inner_gsm": 100, "credits_per_page": 5 },
  "estimated_euro": 4.4
}

Then place the order. Only brochures with status active can be sent. The country defaults to NL.

Place an order
curl -X POST https://slimfolderen.nl/api/v1/orders \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2b8e-1d4a-4f0e-9b3a-2c7d5e8f9a10" \
  -d '{
    "brochure_id": "9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34",
    "recipient_name": "Jan Jansen",
    "recipient_company": "Jansen Installatietechniek B.V.",
    "recipient_address": "Keizersgracht 1",
    "recipient_postal_code": "1015 CJ",
    "recipient_city": "Amsterdam",
    "recipient_country": "NL",
    "external_reference": "crm-4711"
  }'
Response
HTTP/1.1 201 Created

{
  "message": "Brochure succesvol ingepland voor verzending!",
  "order": {
    "id": "0b8f3f9e-2c4d-4e1a-8f57-6a9d2e1c7b40",
    "status": "queued",
    "quantity": 1,
    "total_credits": 22,
    "recipient_name": "Jan Jansen",
    "external_reference": "crm-4711",
    "brochure": "Productbrochure 2026",
    "created_at": "2026-10-27T09:15:02.000000Z"
  },
  "credit_balance": 978
}

With external_reference (up to 100 characters) you give the order your own reference, such as a CRM or order number. It comes back in every response and you can use it to look up orders. The Idempotency-Key makes it safe to resend the request after a time-out; see Retrying safely.

For multiple recipients, use POST /orders/batch with a list of recipients, each with its own external_reference if you like. Recipients at the same address go together in one envelope. The response is 201 if everything succeeded and 207 if some of it failed; those recipients are listed in failed, with their index and external_reference.

If a batch for the same brochure reaches enough different addresses, batch discount applies to every shipment, on the postage only. The threshold and percentage are in batch_discount of GET /pricing; POST /orders/estimate shows whether the discount applies. To let shipments wait until the batch is full, send save_for_batch: true, optionally with send_by (YYYY-MM-DD) as the latest send date. The order gets status saved: you pay the normal price now, and as soon as the batch is full everything goes to the printer and the discount is returned as credit. If the batch is not full by the latest date, the order is sent without discount. Saved orders are not covered by the 2-working-day delivery promise; that applies from the moment they leave.

Retrieve the status
curl https://slimfolderen.nl/api/v1/orders/0b8f3f9e-2c4d-4e1a-8f57-6a9d2e1c7b40 \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"
StatusMeaning
savedSaved for a batch: waiting for batch discount, until the chosen send date at the latest.
queuedScheduled, waiting for the printer.
printingBeing printed.
printedPrinted and folded.
ready_to_shipReady for shipping.
shippedShipped.
deliveredDelivered.
failedFailed. Please contact us.
cancelledCancelled.
The same in JavaScript (Node 18+)
import { randomUUID } from 'node:crypto';

// One idempotency key per order. Store it and reuse the same key on every retry.
const idempotencyKey = randomUUID();

const response = await fetch('https://slimfolderen.nl/api/v1/orders', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SLIMFOLDEREN_API_KEY}`,
    Accept: 'application/json',
    'Content-Type': 'application/json',
    'Idempotency-Key': idempotencyKey,
  },
  body: JSON.stringify({
    brochure_id: '9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34',
    recipient_name: 'Jan Jansen',
    recipient_address: 'Keizersgracht 1',
    recipient_postal_code: '1015 CJ',
    recipient_city: 'Amsterdam',
    external_reference: 'crm-4711',
  }),
});

const data = await response.json();
if (!response.ok) {
  // 422: data.errors per field, e.g. data.errors.credits when there is not enough credit
  throw new Error(data.message);
}
console.log(data.order.id, data.order.status);

Retrying safely

A placed order is printed and costs credit. If you get no response, for example because of a time-out, you cannot tell whether the order has already been created. So send an Idempotency-Key with POST /orders and POST /orders/batch: a unique value of your own for each order or batch, such as a UUID. You can then safely retry with the same idempotency key and the same body.

  • The same idempotency key with the same body returns the first response for 24 hours: the same status and body, with the header Idempotent-Replayed: true. No second order is created and nothing extra is charged. So for a batch that returned a 207, the recipients that succeeded are not sent again.
  • Idempotency keys apply per API key. The same idempotency key with a different body or on a different endpoint returns a 422.
  • If the first request is still running, you get a 409 with Retry-After. Wait that number of seconds and try again.
  • A 4xx is not stored, because nothing was created. After topping up your credit or correcting a field, for example, you reuse the same idempotency key.
  • A 5xx is stored, because a batch may already have been partly sent. A 409 without Retry-After means that the first request was aborted. In both cases, use external_reference to check what has been created, and send the rest with a new idempotency key.
Retried with the same idempotency key
HTTP/1.1 201 Created
Idempotent-Replayed: true

{ ...the same response as the first time... }
Look up an order by your own reference
curl "https://slimfolderen.nl/api/v1/orders?external_reference=crm-4711" \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"

Uploading documents

You upload your own PDF, for a brochure or a letter, in three steps. The key needs the documents:upload scope, and the colleague who owns the key needs the “Upload” team permission.

  1. Start an upload with POST /documents/upload-url. You get back an upload_token, an upload_url and a mode. The upload session is valid for 15 minutes.
  2. Send the PDF to the upload_url. With mode: presigned, that is a PUT with the PDF bytes and Content-Type: application/pdf, without an Authorization header: the upload_url is a temporary storage URL. With mode: direct, it is a POST as multipart/form-data with the field pdf, and this time with your key as the bearer token.
  3. Poll GET /documents/upload-status/{token} every 2 seconds until the status is passed. The number of pages is then in page_count. With failed you get a 422 with the reason in failure_reason; start a new upload in that case.
Start an upload
curl -X POST https://slimfolderen.nl/api/v1/documents/upload-url \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"
Response
{
  "upload_token": "3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43",
  "mode": "presigned",
  "upload_url": "https://…",
  "expires_at": "2026-11-04T09:45:00+00:00"
}
Send the PDF
# mode "presigned": PUT to the storage URL, without an Authorization header
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @brochure.pdf

# mode "direct": POST as multipart/form-data, with your API key
curl -X POST "$UPLOAD_URL" \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -F "pdf=@brochure.pdf"
Retrieve the status
curl https://slimfolderen.nl/api/v1/documents/upload-status/3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43 \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json"
Response
{
  "upload_token": "3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43",
  "status": "passed",
  "page_count": 8,
  "suggested_format": "A4",
  "detected": true,
  "failure_reason": null,
  "expires_at": "2026-11-04T09:45:00+00:00"
}

Every PDF is scanned before you can use it. Only A4 files up to 100 MB pass, without scripts or embedded files. A letter PDF can also have no more than 2 pages.

With the upload_token you then create a brochure, or a letter (see Attaching letters). A token can be used once, within the 15 minutes of the upload session, and only with a key of the same colleague.

Create a brochure
curl -X POST https://slimfolderen.nl/api/v1/brochures \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Productbrochure 2026",
    "upload_token": "3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43",
    "format": "A4",
    "pages": 8,
    "paper_tier": "standard"
  }'

A brochure needs title, format: A4 and pages. pages must equal the page_count of the upload: 2, 4 or a multiple of 4 up to 80. Optional fields are description, visibility and paper_tier (budget, standard or premium; the default is standard). You get a 201 with the brochure. It has status active straight away, so it can be sent immediately.

Attaching letters

A letter can go with a brochure: A4, unfolded, single- or double-sided, in the envelope with the booklet. A letter is either your own PDF (kind: pdf) or a text with fields (kind: text) that we lay out for each recipient, with logo, sender, address block, place and date, subject line and the text.

Attaching letters is being switched on in phases. Check enabled in GET /letters/settings to see whether it is on for you. As long as it is false, an order with a letter_id returns a 422. Creating letters and previews already work. The same endpoint also returns the price per sheet (credits_per_sheet), the typefaces, the font sizes and the standard fields.

Creating a letter

Create a text letter with POST /letters (scope letters:write). title, kind: text and body, the text of up to 8000 characters, are required. A blank line starts a new paragraph; **bold** and *italic* work. You can also send:

  • subject: the subject line.
  • typography: zakelijk (business, the default), klassiek (classic), modern, elegant, vriendelijk (friendly) or eenvoudig (simple).
  • font_size: klein (small, 10 pt), normaal (normal, 11 pt, the default) or groot (large, 12 pt).
  • duplex: print double-sided (default false).
  • logo_id: the id of an envelope logo, which then appears at the top of the letter.
  • show_sender_block and show_address_block: show the sender and the address block (default true).

If the text takes up more than 2 pages, or uses an unknown field, you get a 422 on body. For your own PDF, send kind: pdf, a title and the upload_token of an approved upload (see Uploading documents), optionally with duplex.

Create a text letter
curl -X POST https://slimfolderen.nl/api/v1/letters \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Opvolging beurs",
    "kind": "text",
    "subject": "Ons gesprek op de beurs",
    "body": "{{ontvanger.aanhef}},\n\nBedankt voor uw bezoek aan {{veld.stand|onze stand}}. Uw accountmanager {{veld.accountmanager}} belt u volgende week.\n\nMet vriendelijke groet,\n{{afzender.naam}}",
    "typography": "zakelijk",
    "font_size": "normaal"
  }'
Response
HTTP/1.1 201 Created

{
  "message": "Brief opgeslagen.",
  "letter": {
    "id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56",
    "title": "Opvolging beurs",
    "kind": "text",
    "status": "active",
    "format": "A4",
    "duplex": false,
    "pages": 1,
    "sheets": 1,
    "estimated_credits": 5,
    "fields": {
      "standard": ["ontvanger.aanhef", "afzender.naam"],
      "custom": ["stand", "accountmanager"]
    }
  }
}

Fields

Fields go between double curly braces, such as {{ontvanger.voornaam}}. After a pipe you can add fallback text for when the field is empty: {{veld.stand|onze stand}}. The field names are Dutch (ontvanger = recipient, afzender = sender, veld = field, datum = date). We fill in these standard fields ourselves:

FieldValue
{{ontvanger.aanhef}}Salutation: “Beste <first name>” (Dear …); without a name “Geachte heer/mevrouw” (Dear Sir or Madam).
{{ontvanger.naam}}The recipient’s name.
{{ontvanger.voornaam}}The first word of the name.
{{ontvanger.achternaam}}The rest of the name.
{{ontvanger.bedrijf}}The recipient’s company.
{{ontvanger.adres}}Street and house number.
{{ontvanger.postcode}}Postcode.
{{ontvanger.plaats}}Town or city.
{{afzender.naam}}Name of the colleague who owns the key.
{{afzender.email}}Their email address.
{{afzender.telefoon}}Their phone number, otherwise your company’s.
{{afzender.bedrijf}}Your company name.
{{afzender.adres}}Your company’s address. The sender and address blocks follow the sender and recipient fields, so a value in letter_fields changes them too.
{{afzender.postcode}}Your company’s postcode.
{{afzender.plaats}}Your company’s town or city, also shown with the date.
{{datum}}The date the order is placed, in Dutch, for example “4 november 2026”.

You write a custom field as {{veld.<name>}}. You pass its value with each order in letter_fields. If a custom field without fallback text has no value, the order returns a 422 on letter_fields. The custom fields a letter uses are listed in fields.custom of the letter.

Preview

GET /letters/{id}/pdf returns a preview PDF. A text letter is filled with sample data; override it in the query with letter_fields[name]=… and recipient[recipient_name]=…. A PDF letter returns the file itself. A field without a value and without fallback text appears in the preview between brackets, such as [veld.accountmanager].

POST /letters/preview creates a preview of a text letter that has not been saved yet: the same fields as when creating one, plus optional letter_fields and recipient. The response is the PDF; the X-Letter-Pages and X-Letter-Sheets headers give the number of pages and sheets.

Retrieve a preview PDF
curl -G https://slimfolderen.nl/api/v1/letters/5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56/pdf \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  --data-urlencode "letter_fields[accountmanager]=Piet" \
  --data-urlencode "recipient[recipient_name]=Jan Jansen" \
  -o proef.pdf

Attaching a letter to an order

Send a letter_id with POST /orders and, for a text letter, letter_fields with the values. A key without a prefix is a custom field: {"accountmanager": "Piet"} fills {{veld.accountmanager}}. A standard field overrides the calculated value, such as {"ontvanger.aanhef": "Geachte heer Jansen"}. Nested objects work too: {"ontvanger": {"aanhef": "…"}}.

Order with a letter
curl -X POST https://slimfolderen.nl/api/v1/orders \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c4d1e2f-3a5b-4c6d-9e7f-0a1b2c3d4e5f" \
  -d '{
    "brochure_id": "9d3c4a52-7f1e-4b8a-9c61-2f0e8b7a1d34",
    "recipient_name": "Jan Jansen",
    "recipient_address": "Keizersgracht 1",
    "recipient_postal_code": "1015 CJ",
    "recipient_city": "Amsterdam",
    "letter_id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56",
    "letter_fields": {
      "accountmanager": "Piet",
      "ontvanger.aanhef": "Geachte heer Jansen"
    }
  }'
Response
HTTP/1.1 201 Created

{
  "message": "Brochure succesvol ingepland voor verzending!",
  "order": {
    "id": "7e1b9c3a-4d2f-4a8e-b6c5-1f0d9e8a7b62",
    "status": "queued",
    "total_credits": 27,
    "recipient_name": "Jan Jansen",
    "brochure": "Productbrochure 2026",
    "letter": { "id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56", "title": "Opvolging beurs", "pages": 1, "sheets": 1, "credits": 5 },
    "created_at": "2026-11-04T10:02:11.000000Z"
  },
  "credit_balance": 951
}

With POST /orders/batch, letter_id and letter_fields apply to all recipients; recipients[].letter_fields adds to or overrides them per recipient. If a recipient is missing a field, it ends up in failed and the response is a 207. With letter_id in POST /orders/estimate, the cost of the letter is in letter_credits, calculated with the pages of the letter itself.

A letter costs credits_per_sheet × the number of sheets. Single-sided, each page is a sheet; double-sided, two pages fit on a sheet, rounded up. One letter goes with each order. For a bulk order (quantity greater than 1) that means one letter per shipment. The batch discount does not apply to the letter, only to the postage. A text letter is laid out for each recipient, and the order is charged for the pages of that laid-out letter.

A letter that cannot be attached returns a 422 on letter_id, with “Brief bijvoegen is nog niet beschikbaar.” (attaching letters is not available yet) or “Deze brief bestaat niet of is gearchiveerd.” (this letter does not exist or has been archived). A text letter that takes up more than 2 pages for this recipient also returns an error there.

GET /orders/{id} shows letter_id, letter_fields, letter_pages, letter_sheets, letter_credits, letter and letter_pdf_available. With GET /orders/{id}/letter you retrieve the letter PDF as it was laid out for this recipient.

Changing and deleting

With PATCH /letters/{id} you change title, status (active or archived), duplex and, for a text letter, the text fields. For a PDF letter, a new upload_token replaces the PDF. DELETE /letters/{id} deletes and archives the letter. Only active letters can be attached; orders that have already been placed keep their letter. Creating a letter needs the “Upload” team permission for the colleague who owns the key; changing and deleting needs the “Bewerken” (Edit) team permission.

Sending one-pagers

A one-pager is a letter sent on its own, without a booklet: one A4 sheet on 210 gsm paper, single- or double-sided, flat in the envelope. You use the same letters as for attaching letters: text with fields or your own PDF. It must fit on one sheet: one page single-sided or two pages double-sided.

One-pagers are being rolled out gradually. Check onepager.enabled in GET /letters/settings to see whether it is on for you. It also lists the paper weight (gsm), the print cost per sheet and the shipping rate per country.

Send a one-pager
curl -X POST https://slimfolderen.nl/api/v1/onepagers \
  -H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f9a1c7e-2b4d-4e6f-8a0c-5d7e9f1b3c2a" \
  -d '{
    "letter_id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56",
    "letter_fields": { "accountmanager": "Piet" },
    "recipient_name": "Jan Jansen",
    "recipient_address": "Keizersgracht 1",
    "recipient_postal_code": "1015 CJ",
    "recipient_city": "Amsterdam"
  }'
Response
HTTP/1.1 201 Created

{
  "message": "Onepager succesvol ingepland voor verzending!",
  "order": {
    "id": "8f2c0d4b-5e3a-4b9f-c7d6-2a1e0f9b8c73",
    "kind": "onepager",
    "status": "queued",
    "total_credits": 24,
    "letter_credits": 5,
    "shipping_credits": 19,
    "recipient_name": "Jan Jansen",
    "letter": { "id": "5a7e2c14-8b3d-4f6a-9e21-7c0d4b8a3f56", "title": "Opvolging beurs", "pages": 2, "sheets": 1, "credits": 5 },
    "paper": { "format": "A4", "gsm": 210, "duplex": true, "sheets": 1, "folded": false },
    "created_at": "2026-11-04T10:02:11.000000Z"
  },
  "credit_balance": 927
}

A one-pager costs the print cost of the sheet (onepager.credits_per_sheet) plus its own shipping rate, lower than a booklet's: 19 credits within the Netherlands, 29 to Belgium, 39 to Germany and 59 elsewhere. No bulk orders, saving or batch discount.

POST /onepagers/batch sends the same one-pager to up to 100 recipients, with shared letter_fields and recipients[].letter_fields per recipient. Recipients at the same address share one envelope, so shipping counts once. POST /onepagers/estimate calculates the cost up front, with recipient_country or a list of recipients.

A one-pager is a regular order with kind onepager and no brochure_id. Track it with GET /orders/{id}; GET /orders?kind=onepager lists only one-pagers. A letter longer than one sheet returns a 422 on letter_id, as does a text letter that runs onto a second sheet for a recipient.

Errors

Errors are returned as JSON with a message. With a 422, errors shows what is wrong with each field. The text of message and of the field errors is in Dutch; rely on the status code and field names in your code.

  • 401No key, or an invalid, expired or revoked key.
  • 403The key lacks the scope (see required_scopes), the endpoint is not available to API keys, or the owner of the key is not authorised to use it.
  • 404Does not exist or does not belong to your company.
  • 409A request with the same Idempotency-Key is still being processed or was aborted.
  • 422Invalid input, a brochure that cannot be sent, a letter that cannot be attached (errors.letter_id or errors.letter_fields), insufficient credit (errors.credits) or an Idempotency-Key that has already been used for a different request (errors.idempotency_key).
  • 429Rate limit reached. Wait the number of seconds given in the Retry-After header.
Missing scope
HTTP/1.1 403 Forbidden

{
  "message": "Deze API-sleutel mist de benodigde scope.",
  "required_scopes": ["orders:create"]
}

Rate limits

Each key can make 60 requests per minute. In addition, a single user can place up to 60 orders and 20 batches per minute, start up to 10 uploads and create up to 10 brochures per minute. Creating and changing letters and retrieving preview PDFs is limited to 30 times per minute. Polling the upload status counts towards the 60 requests per key. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining. With a 429, Retry-After tells you after how many seconds you can try again.

OpenAPI specification

All endpoints, fields and responses are described in the OpenAPI 3.1 specification. Import it into Postman, Insomnia or a code generator.

Prefer not to write code? With webhooks you can connect your CRM, Zapier or Make without any programming.