curl --request POST \
--url https://api.smartsend.io/v2/teams/{teamUuid}/booking-batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reference": "MORNING-2026-09-16",
"identifier": "batch-db-42"
}
'{
"data": {
"uuid": "55555555-5555-4555-8555-555555555555",
"state": "open",
"identifier": "batch-db-42",
"reference": "MORNING-2026-09-16",
"total_count": 0,
"pending_count": 0,
"processing_count": 0,
"booked_count": 0,
"failed_count": 0,
"cancelled_count": 0,
"completed_count": 0,
"progress": 0,
"callback": null,
"created_at": "2026-09-16T10:00:00Z",
"updated_at": "2026-09-16T10:00:00Z",
"started_at": null,
"finished_at": null
}
}{
"message": "Unauthenticated."
}{
"message": "This action is unauthorized."
}{
"message": "A request with this Idempotency-Key is still being processed."
}{
"message": "The given data was invalid.",
"errors": {
"field_name": [
"This field is required."
]
}
}{
"message": "Too Many Attempts."
}{
"message": "Server Error"
}{
"message": "Service Unavailable"
}Create a booking batch
Create an empty open batch, optionally with a signed callback limited to its members and batch progress. No shipments are booked until start. Add shipments through the batch shipments endpoint.
curl --request POST \
--url https://api.smartsend.io/v2/teams/{teamUuid}/booking-batches \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"reference": "MORNING-2026-09-16",
"identifier": "batch-db-42"
}
'{
"data": {
"uuid": "55555555-5555-4555-8555-555555555555",
"state": "open",
"identifier": "batch-db-42",
"reference": "MORNING-2026-09-16",
"total_count": 0,
"pending_count": 0,
"processing_count": 0,
"booked_count": 0,
"failed_count": 0,
"cancelled_count": 0,
"completed_count": 0,
"progress": 0,
"callback": null,
"created_at": "2026-09-16T10:00:00Z",
"updated_at": "2026-09-16T10:00:00Z",
"started_at": null,
"finished_at": null
}
}{
"message": "Unauthenticated."
}{
"message": "This action is unauthorized."
}{
"message": "A request with this Idempotency-Key is still being processed."
}{
"message": "The given data was invalid.",
"errors": {
"field_name": [
"This field is required."
]
}
}{
"message": "Too Many Attempts."
}{
"message": "Server Error"
}{
"message": "Service Unavailable"
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Preferred language(s) for translatable content using BCP 47 language tags. Supports quality values (q-factors) for priority ordering. The API negotiates the best available language based on this header, the team's configured language, and available translations. If omitted, the team's default language is used.
"da-DK, da;q=0.9, en;q=0.8"
Optional client-supplied request identifier. When provided and matching the validation pattern, the value is echoed back in the Request-ID response header. Otherwise the server generates one. Use this to correlate requests between client and server when reporting issues.
1 - 64^[A-Za-z0-9._-]{1,64}$Optional, case-sensitive key for one intended action. Scope: team, HTTP method and canonical path. Retained for at least 24 hours and while processing. Same key and payload reuses the stored outcome without repeating side effects; the resource representation is current. Changed payload: 422 with an Idempotency-Key entry in errors. Concurrent duplicate: 409 with Retry-After and Location when known. Without a key there is no deduplication. Use GET at Location after 202.
16 - 128^[A-Za-z0-9._-]{16,128}$Path Parameters
Team uuid. All resources are scoped to this team.
Body
Create an empty open batch. Team document/print defaults apply to each shipment at its acceptance.
Private integration reference.
Public batch reference.
Register a callback at batch creation. Omitted events defaults to shipment.booked, shipment.failed, shipment.cancelled, shipment.voided, batch.completed and batch.stopped. Callback configuration is immutable after creation.
Show child attributes
Show child attributes
Callbacks
POST{$request.body#/callback/url}updates
Body
- Option 1
- Option 2
Thin event envelope: stable id, event type, occurred_at, team_uuid and resource identifiers in data. Full payloads are not offered in this version. A future full-payload option must be explicitly selected; existing thin subscriptions retain their documented meaning.
Stable event UUID, also sent in webhook-id. Duplicate deliveries keep the same id.
When the business event occurred; distinct from the delivery-attempt timestamp.
Resource UUID.
shipment.booked, shipment.failed, shipment.cancelled, shipment.voided Show child attributes
Show child attributes
Response
Event durably accepted. Other 2xx responses also acknowledge delivery.
Response
Open batch created.
Batch progress for one-at-a-time booking. total_count = pending_count + processing_count + completed_count. Post-booking cancellation/printing/tracking do not rewrite booking outcomes. Late booking corrections may adjust outcome counts without reopening a terminal batch.
Show child attributes
Show child attributes
Was this page helpful?