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
- Log in and go to “Integraties” → “API-sleutels” (Integrations → API keys). You need the “Integraties” (Integrations) team permission for this.
- 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.
- 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:
| Scope | Gives 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
/brochuresBrochures, newest first. Filters: status, format, search.
Scope:
brochures:read - GET
/brochures/{id}A single brochure.
Scope:
brochures:read - POST
/documents/upload-urlStart 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
/brochuresCreate a brochure from an approved upload.
Scope:
documents:upload - GET
/letters/settingsWhether attaching letters is enabled, the price per sheet, typefaces and standard fields.
Scope:
letters:read - GET
/lettersLetters, newest first. Filter: status (active or archived).
Scope:
letters:read - POST
/lettersCreate a letter: text with fields, or your own PDF.
Scope:
letters:write - POST
/letters/previewPreview 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}/pdfPreview PDF of a saved letter.
Scope:
letters:read - POST
/orders/estimateCalculate the cost without sending anything.
Scope:
orders:create - POST
/ordersPlace one order (or a bulk order to one address).
Scope:
orders:create - POST
/orders/batchThe same brochure to up to 100 recipients.
Scope:
orders:create - POST
/onepagers/estimateCalculate the cost of a one-pager without sending anything.
Scope:
orders:create - POST
/onepagersSend a letter on its own as a one-pager: one A4 sheet, no booklet.
Scope:
orders:create - POST
/onepagers/batchThe same one-pager to up to 100 recipients.
Scope:
orders:create - GET
/ordersOrders, 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}/letterThe letter PDF as it goes with this order.
Scope:
orders:read - GET
/orders/savedSaved orders per brochure: how many addresses are waiting and when the first leaves at the latest.
Scope:
orders:read - POST
/orders/{id}/send-nowSend a saved order now, without batch discount.
Scope:
orders:create - POST
/orders/{id}/cancel-savedCancel a saved order; the credit is returned.
Scope:
orders:create - GET
/campaignsWebhook 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:
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"}'{
"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.
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"
}'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.
curl https://slimfolderen.nl/api/v1/orders/0b8f3f9e-2c4d-4e1a-8f57-6a9d2e1c7b40 \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json"| Status | Meaning |
|---|---|
saved | Saved for a batch: waiting for batch discount, until the chosen send date at the latest. |
queued | Scheduled, waiting for the printer. |
printing | Being printed. |
printed | Printed and folded. |
ready_to_ship | Ready for shipping. |
shipped | Shipped. |
delivered | Delivered. |
failed | Failed. Please contact us. |
cancelled | Cancelled. |
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-Aftermeans that the first request was aborted. In both cases, useexternal_referenceto check what has been created, and send the rest with a new idempotency key.
HTTP/1.1 201 Created
Idempotent-Replayed: true
{ ...the same response as the first time... }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.
- Start an upload with
POST /documents/upload-url. You get back anupload_token, anupload_urland amode. The upload session is valid for 15 minutes. - Send the PDF to the
upload_url. Withmode: presigned, that is a PUT with the PDF bytes andContent-Type: application/pdf, without an Authorization header: theupload_urlis a temporary storage URL. Withmode: direct, it is a POST asmultipart/form-datawith the fieldpdf, and this time with your key as the bearer token. - Poll
GET /documents/upload-status/{token}every 2 seconds until the status ispassed. The number of pages is then inpage_count. Withfailedyou get a 422 with the reason infailure_reason; start a new upload in that case.
curl -X POST https://slimfolderen.nl/api/v1/documents/upload-url \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json"{
"upload_token": "3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43",
"mode": "presigned",
"upload_url": "https://…",
"expires_at": "2026-11-04T09:45:00+00:00"
}# 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"curl https://slimfolderen.nl/api/v1/documents/upload-status/3f2a9c1e-5b7d-4e8f-a1c2-9d0e7b6a5f43 \
-H "Authorization: Bearer $SLIMFOLDEREN_API_KEY" \
-H "Accept: application/json"{
"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.
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) oreenvoudig(simple).font_size:klein(small, 10 pt),normaal(normal, 11 pt, the default) orgroot(large, 12 pt).duplex: print double-sided (defaultfalse).logo_id: the id of an envelope logo, which then appears at the top of the letter.show_sender_blockandshow_address_block: show the sender and the address block (defaulttrue).
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.
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"
}'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:
| Field | Value |
|---|---|
{{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.
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.pdfAttaching 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": "…"}}.
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"
}
}'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.
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"
}'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.
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.
