POST/v1/postbatches/{id}/import

Upload the CSV of a Postbatch

Attaches a completed csv upload (DRAFT or VALIDATED; a previous import is replaced) and starts the parse: encoding and delimiter detection, header checks, the row limit, a sample and a mapping proposal from the template presets or the header names. Pass a mapping to skip the proposal. Poll GET .../import.

Scope postbatches.write

Path parameters

idstringrequired

Body

uploadIdstringrequiredmin length 1max length 40

mappingobject

Returns

22 fields of the 202 answer

idstringrequired

postbatchIdstringrequired

uploadIdstringrequired

statusenumrequired

UPLOADEDPARSINGPARSEDMAPPEDPROCESSINGDONEFAILEDCANCELLED

encodingstring or nullrequired

delimiterstring or nullrequired

headersarray of stringrequired

sampleRowsarray of objectsrequired

rowCountinteger or nullrequired

malformedRowsarray of integerrequired

targetsarray of objectsrequired

3 fields

namestringrequired

requiredbooleanrequired

kindenumrequired

recipientvariable

proposedMappingobject or nullrequired

mappingSourcestring or nullrequired

mappingobject or nullrequired

issuesarray of objectsrequired

5 fields

codeenumrequired

unknown_targetunknown_columnunmapped_requiredunused_columnempty_expression

severityenumrequired

errorwarning

messagestringrequired

targetstring

columnstring

rowCountsobjectrequired

errorsarray of objectsrequired

3 fields

codestringrequired

messagestringrequired

lineinteger

parsedAtdate-time or nullrequired

startedAtdate-time or nullrequired

finishedAtdate-time or nullrequired

createdAtdate-timerequired

updatedAtdate-timerequired

Responses

202Success

401Authentication required or API key invalid

403Permission or scope missing, organisation suspended

404Not found

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/postbatches/pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K/import \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "uploadId": "upl_01J9Y2K8QF4T6W8Z0B2D4F6H8K" }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.postbatches.startImport('pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K', { body: { uploadId: 'upl_01J9Y2K8QF4T6W8Z0B2D4F6H8K', }, });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.postbatches.start_import("pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K", { "uploadId": "upl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", })

{ "id": "ipt_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "postbatchId": "pb_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "uploadId": "upl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "status": "UPLOADED", "encoding": "Example", "delimiter": "Example", "headers": [ "Example" ], "sampleRows": [ { "key": "first_name" } ], "rowCount": 3, "malformedRows": [ 1 ], "targets": [ { "name": "Welcome card", "required": false, "kind": "recipient" } ], "proposedMapping": { "key": "first_name" }, "mappingSource": "Example", "mapping": { "key": "first_name" }, "issues": [ { "code": "unknown_target", "severity": "error", "message": "The postal code is not valid", "target": "Example", "column": "Example" } ], "rowCounts": { "key": 1 }, "errors": [], "parsedAt": "2026-10-16T09:14:02.000Z", "startedAt": "2026-10-16T09:14:02.000Z", "finishedAt": "2026-10-16T09:14:02.000Z", "createdAt": "2026-10-16T09:14:02.000Z", "updatedAt": "2026-10-16T09:14:02.000Z" }

{ "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" } ] }