POST/v1/uploads

Create an upload session with a presigned PUT URL

Scope templates.writeIdempotent with a keyRate limit class upload

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

imagefontcsvattachment

fileNamestringrequiredmin length 1max length 200

contentTypestringrequiredmin length 3max length 100

sizeBytesintegerrequired

sha256string

licenceConfirmedboolean

Returns

15 fields of the 201 answer

idstringrequired

kindenumrequired

imagefontcsvattachment

fileNamestringrequired

contentTypestringrequired

sizeBytesintegerrequired

statusenumrequired

PENDINGUPLOADEDPROCESSINGREADYREJECTEDEXPIRED

rejectionobject or nullrequired

2 fields

codestringrequired

reasonstring or nullrequired

resultIdstring or nullrequired

expiresAtdate-timerequired

completedAtdate-time or nullrequired

processedAtdate-time or nullrequired

createdAtdate-timerequired

urlstringrequired

methodstringrequired

headersobjectrequired

Responses

201Success

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/uploads \ -H "Authorization: Bearer $POSTBUDDY_API_KEY" \ -H "Idempotency-Key: crm-0062p00001Xyz-signed" \ -H "Content-Type: application/json" \ -d '{ "kind": "image", "fileName": "customers.csv", "contentType": "Example", "sizeBytes": 1 }'

import { PostBuddyClient } from '@postbuddy/sdk'; const client = new PostBuddyClient({ apiKey: process.env.POSTBUDDY_API_KEY! }); const result = await client.uploads.create({ body: { kind: 'image', fileName: 'customers.csv', contentType: 'Example', sizeBytes: 1, },, idempotencyKey: 'crm-0062p00001Xyz-signed', });

import os from postbuddy import Client client = Client(os.environ["POSTBUDDY_API_KEY"]) result = client.uploads.create({ "kind": "image", "fileName": "customers.csv", "contentType": "Example", "sizeBytes": 1, }, idempotency_key="crm-0062p00001Xyz-signed")

{ "id": "upl_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "kind": "image", "fileName": "customers.csv", "contentType": "Example", "sizeBytes": 1, "status": "READY", "rejection": { "code": "validation_failed", "reason": "Example" }, "resultId": "obj_01J9Y2K8QF4T6W8Z0B2D4F6H8K", "expiresAt": "2026-10-16T09:14:02.000Z", "completedAt": "2026-10-16T09:14:02.000Z", "processedAt": "2026-10-16T09:14:02.000Z", "createdAt": "2026-10-16T09:14:02.000Z", "url": "https://example.com/r/Fq3ZtR8w", "method": "PUT", "headers": { "key": "first_name" } }

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