{ "openapi": "3.1.0", "info": { "title": "PostBuddy API", "version": "1.0.0", "description": "Direct mail as an API: templates, Postflows, items and Postbatches. Authenticate with an organisation API key as a bearer token.", "x-audience": "public" }, "x-rate-limits": { "description": "Per API key, fixed one-minute windows per class; general applies unless x-rate-limit-class says otherwise; admins can override per organisation.", "defaults": { "general": 600, "itemCreate": 3000, "preview": 60, "upload": 60, "export": 20, "invite": 30, "public": 60 } }, "servers": [ { "url": "https://api.postbuddy.nl" } ], "tags": [ { "name": "AdvertisingCategories" }, { "name": "Analytics" }, { "name": "Billing" }, { "name": "Developers" }, { "name": "Exports" }, { "name": "Integrations" }, { "name": "Items" }, { "name": "MappingPresets" }, { "name": "Media" }, { "name": "Meta" }, { "name": "Organisation" }, { "name": "Organisations" }, { "name": "PlatformAssets" }, { "name": "Postbatches" }, { "name": "Postflows" }, { "name": "Products" }, { "name": "Renders" }, { "name": "Runs" }, { "name": "Status" }, { "name": "Support" }, { "name": "SuppressionReasons" }, { "name": "Suppressions" }, { "name": "TemplateLibrary" }, { "name": "Templates" }, { "name": "Uploads" }, { "name": "Webhooks" } ], "paths": { "/v1/advertising-categories": { "get": { "operationId": "advertisingCategories.list", "summary": "List advertising categories", "description": "The platform's categories followed by the organisation's own; archived ones are flagged and can no longer be chosen.", "tags": [ "AdvertisingCategories" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "organisation" ] }, "sortOrder": { "type": "integer" }, "archived": { "type": "boolean" } }, "required": [ "key", "label", "source", "sortOrder", "archived" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "post": { "operationId": "advertisingCategories.create", "summary": "Add an advertising category", "description": "The key is derived from the label when absent and cannot equal a platform key.", "tags": [ "AdvertisingCategories" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "key": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{1,40}$" }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "organisation" ] }, "sortOrder": { "type": "integer" }, "archived": { "type": "boolean" } }, "required": [ "key", "label", "source", "sortOrder", "archived" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" } }, "/v1/advertising-categories/{key}": { "patch": { "operationId": "advertisingCategories.patch", "summary": "Rename, reorder or archive an advertising category", "description": "Only the organisation's own categories; a platform category is refused.", "tags": [ "AdvertisingCategories" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 }, "archived": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "organisation" ] }, "sortOrder": { "type": "integer" }, "archived": { "type": "boolean" } }, "required": [ "key", "label", "source", "sortOrder", "archived" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" }, "delete": { "operationId": "advertisingCategories.remove", "summary": "Delete an advertising category", "description": "Refused while a Postflow, Postbatch, item or suppression entry uses it.", "tags": [ "AdvertisingCategories" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Still in use (still_referenced); archive it instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" } }, "/v1/analytics/items.csv": { "get": { "operationId": "analytics.exportCsv", "summary": "Items of a period as CSV", "description": "Up to ten thousand items with their statuses, timestamps and unit prices, newest first; the same filters as the summary.", "tags": [ "Analytics" ], "x-rate-limit-class": "export", "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366 } }, { "name": "postflowId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "postbatchId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "The items as CSV", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/analytics/summary": { "get": { "operationId": "analytics.summary", "summary": "Counters and daily series", "description": "Items by status, QR scans and spend for a period (from and to as dates, or days back, default thirty) and optionally one Postflow or Postbatch, with a row per day.", "tags": [ "Analytics" ], "parameters": [ { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "days", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 366 } }, { "name": "postflowId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "name": "postbatchId", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 40 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "to": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "from", "to" ], "additionalProperties": false }, "filter": { "type": "object", "properties": { "postflowId": { "type": "string" }, "postbatchId": { "type": "string" } }, "additionalProperties": false }, "totals": { "type": "object", "properties": { "created": { "type": "integer" }, "sent": { "type": "integer" }, "scheduled": { "type": "integer" }, "held": { "type": "integer" }, "needsAttention": { "type": "integer" }, "cancelled": { "type": "integer" }, "failed": { "type": "integer" }, "suppressed": { "type": "integer" }, "scans": { "type": "integer" }, "spendCents": { "type": "integer" } }, "required": [ "created", "sent", "scheduled", "held", "needsAttention", "cancelled", "failed", "suppressed", "scans", "spendCents" ], "additionalProperties": false }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer" } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "day": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "created": { "type": "integer" }, "sent": { "type": "integer" }, "cancelled": { "type": "integer" }, "failed": { "type": "integer" }, "scans": { "type": "integer" }, "spendCents": { "type": "integer" } }, "required": [ "day", "created", "sent", "cancelled", "failed", "scans", "spendCents" ], "additionalProperties": false } } }, "required": [ "period", "filter", "totals", "byStatus", "daily" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/assets": { "get": { "operationId": "uploads.assets", "summary": "List image assets", "tags": [ "Uploads" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor of the previous page (same sort and filters).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma separated, prefix - for descending; fields: createdAt, name. Default -createdAt.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "include=total adds totalCount.", "schema": { "type": "string", "enum": [ "total" ] } }, { "name": "filter[name]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[name][contains]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[format]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "jpeg", "png" ] } }, { "name": "filter[format][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[createdAt][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "format": { "type": "string", "enum": [ "jpeg", "png" ] }, "widthPx": { "type": "integer" }, "heightPx": { "type": "integer" }, "hasAlpha": { "type": "boolean" }, "colourProfile": { "type": "string" }, "sizeBytes": { "type": "integer" }, "urls": { "type": "object", "properties": { "master": { "type": "string", "format": "uri" }, "thumb": { "type": "string", "format": "uri" } }, "required": [ "master", "thumb" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "format", "widthPx", "heightPx", "hasAlpha", "colourProfile", "sizeBytes", "urls", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "type": "integer" } }, "required": [ "data", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/assets/{id}": { "get": { "operationId": "uploads.asset", "summary": "Get an image asset with signed URLs", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "format": { "type": "string", "enum": [ "jpeg", "png" ] }, "widthPx": { "type": "integer" }, "heightPx": { "type": "integer" }, "hasAlpha": { "type": "boolean" }, "colourProfile": { "type": "string" }, "sizeBytes": { "type": "integer" }, "urls": { "type": "object", "properties": { "master": { "type": "string", "format": "uri" }, "thumb": { "type": "string", "format": "uri" } }, "required": [ "master", "thumb" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "format", "widthPx", "heightPx", "hasAlpha", "colourProfile", "sizeBytes", "urls", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" }, "delete": { "operationId": "uploads.deleteAsset", "summary": "Delete an image asset", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/billing/invoices": { "get": { "operationId": "invoices.list", "summary": "List invoices and credit notes", "description": "Newest first; top-up invoices are paid at issue, monthly invoices carry the period and the due date.", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "kind": { "type": "string", "enum": [ "INVOICE", "CREDIT_NOTE" ] }, "source": { "type": "string", "enum": [ "TOP_UP", "MONTHLY", "CREDIT" ] }, "status": { "type": "string", "enum": [ "ISSUED", "PAID", "VOID" ] }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "periodFrom": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "periodTo": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "currency": { "type": "string" }, "vatTreatment": { "type": "string", "enum": [ "NL_STANDARD", "EU_REVERSE_CHARGE", "NON_EU" ] }, "vatRate": { "type": "integer" }, "subtotalCents": { "type": "integer" }, "vatCents": { "type": "integer" }, "totalCents": { "type": "integer" }, "paidCents": { "type": "integer" }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "creditNoteOfInvoiceId": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "paymentId": { "type": [ "string", "null" ] }, "hasPdf": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "number", "kind", "source", "status", "issueDate", "dueDate", "periodFrom", "periodTo", "currency", "vatTreatment", "vatRate", "subtotalCents", "vatCents", "totalCents", "paidCents", "paidAt", "sentAt", "creditNoteOfInvoiceId", "reason", "paymentId", "hasPdf", "createdAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/invoices/{id}": { "get": { "operationId": "invoices.get", "summary": "An invoice with its lines", "tags": [ "Billing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "string" }, "kind": { "type": "string", "enum": [ "INVOICE", "CREDIT_NOTE" ] }, "source": { "type": "string", "enum": [ "TOP_UP", "MONTHLY", "CREDIT" ] }, "status": { "type": "string", "enum": [ "ISSUED", "PAID", "VOID" ] }, "issueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "dueDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "periodFrom": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "periodTo": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "currency": { "type": "string" }, "vatTreatment": { "type": "string", "enum": [ "NL_STANDARD", "EU_REVERSE_CHARGE", "NON_EU" ] }, "vatRate": { "type": "integer" }, "subtotalCents": { "type": "integer" }, "vatCents": { "type": "integer" }, "totalCents": { "type": "integer" }, "paidCents": { "type": "integer" }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "creditNoteOfInvoiceId": { "type": [ "string", "null" ] }, "reason": { "type": [ "string", "null" ] }, "paymentId": { "type": [ "string", "null" ] }, "hasPdf": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "integer" }, "kind": { "type": "string", "enum": [ "TOP_UP", "USAGE", "SUBSCRIPTION_FEE", "ADJUSTMENT", "CREDIT" ] }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceCents": { "type": "integer" }, "amountCents": { "type": "integer" }, "vatRate": { "type": "integer" }, "referenceType": { "type": [ "string", "null" ] }, "referenceId": { "type": [ "string", "null" ] } }, "required": [ "id", "position", "kind", "description", "quantity", "unitPriceCents", "amountCents", "vatRate", "referenceType", "referenceId" ], "additionalProperties": false } }, "parties": { "type": "object", "properties": { "seller": { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "kvk": { "type": "string" }, "vatNumber": { "type": "string" }, "iban": { "type": "string" }, "bic": { "type": [ "string", "null" ] } }, "required": [ "name", "addressLine1", "postalCode", "city", "country", "kvk", "vatNumber", "iban", "bic" ], "additionalProperties": false }, "buyer": { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "vatNumber": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "incomplete": { "type": "boolean" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country", "vatNumber", "email", "incomplete" ], "additionalProperties": false } }, "required": [ "seller", "buyer" ], "additionalProperties": false } }, "required": [ "id", "number", "kind", "source", "status", "issueDate", "dueDate", "periodFrom", "periodTo", "currency", "vatTreatment", "vatRate", "subtotalCents", "vatCents", "totalCents", "paidCents", "paidAt", "sentAt", "creditNoteOfInvoiceId", "reason", "paymentId", "hasPdf", "createdAt", "lines", "parties" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/invoices/{id}/pdf": { "get": { "operationId": "invoices.pdf", "summary": "A signed download link for the invoice PDF (ten minutes)", "tags": [ "Billing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/ledger": { "get": { "operationId": "billing.ledger", "summary": "Ledger entries", "description": "Append-only ledger entries newest first with a cursor: top-ups, reservations, releases, charges, refunds, adjustments, subscription fees and invoice payments, each with the amount and what it did to the balance, the reserved and the outstanding figures. Filter on type (comma separated), a period and a reference id (for example an item id).", "tags": [ "Billing" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "allOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "enum": [ "TOP_UP", "RESERVATION", "RELEASE", "CHARGE", "REFUND", "ADJUSTMENT", "SUBSCRIPTION_FEE", "INVOICE_PAYMENT" ] }, "minItems": 1, "maxItems": 8 } ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "referenceId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "TOP_UP", "RESERVATION", "RELEASE", "CHARGE", "REFUND", "ADJUSTMENT", "SUBSCRIPTION_FEE", "INVOICE_PAYMENT" ] }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "balanceDeltaCents": { "type": "integer" }, "reservedDeltaCents": { "type": "integer" }, "outstandingDeltaCents": { "type": "integer" }, "referenceType": { "anyOf": [ { "type": "string", "enum": [ "item", "postbatch", "run", "invoice", "payment" ] }, { "type": "null" } ] }, "referenceId": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "metadata": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "PREPAID", "TRIAL", "INVOICE" ] }, "listAmountCents": { "type": "integer" }, "productId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "runId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "postflowId": { "type": [ "string", "null" ] }, "subscriptionId": { "type": "string" }, "planId": { "type": "string" }, "month": { "type": "string" }, "invoiceVat": { "type": "boolean" }, "invoiceNumber": { "type": "string" }, "creditNoteOf": { "type": "string" }, "reason": { "type": "string" }, "method": { "type": "string", "enum": [ "BANK_TRANSFER", "OTHER" ] }, "paidAt": { "type": "string", "format": "date-time" } }, "additionalProperties": false }, "actorType": { "type": "string", "enum": [ "USER", "API_KEY", "ADMIN", "SYSTEM" ] }, "actorId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "amountCents", "currency", "balanceDeltaCents", "reservedDeltaCents", "outstandingDeltaCents", "referenceType", "referenceId", "description", "metadata", "actorType", "actorId", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/payments": { "get": { "operationId": "billing.payments", "summary": "Payments", "description": "Top-up requests and registered payments of the organisation newest first, with status PENDING, COMPLETED or CANCELLED and the ledger entry a completed payment posted.", "tags": [ "Billing" ], "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELLED" ] } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "TOP_UP", "INVOICE_PAYMENT" ] }, "provider": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELLED" ] }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "method": { "anyOf": [ { "type": "string", "enum": [ "BANK_TRANSFER", "OTHER" ] }, { "type": "null" } ] }, "reference": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "invoiceId": { "type": [ "string", "null" ] }, "ledgerEntryId": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "requestedByType": { "type": "string", "enum": [ "USER", "API_KEY", "ADMIN", "SYSTEM" ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "provider", "status", "amountCents", "currency", "method", "reference", "externalReference", "paidAt", "invoiceId", "ledgerEntryId", "notes", "requestedByType", "completedAt", "cancelledAt", "createdAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/payments/{id}/cancel": { "post": { "operationId": "billing.cancelPayment", "summary": "Cancel a pending top-up request", "description": "Only pending requests can be cancelled; a registered payment stays.", "tags": [ "Billing" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "TOP_UP", "INVOICE_PAYMENT" ] }, "provider": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELLED" ] }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "method": { "anyOf": [ { "type": "string", "enum": [ "BANK_TRANSFER", "OTHER" ] }, { "type": "null" } ] }, "reference": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "invoiceId": { "type": [ "string", "null" ] }, "ledgerEntryId": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "requestedByType": { "type": "string", "enum": [ "USER", "API_KEY", "ADMIN", "SYSTEM" ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "provider", "status", "amountCents", "currency", "method", "reference", "externalReference", "paidAt", "invoiceId", "ledgerEntryId", "notes", "requestedByType", "completedAt", "cancelledAt", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.manage" } }, "/v1/billing/prices": { "get": { "operationId": "pricing.prices", "summary": "Your prices", "description": "The effective price rules for the organisation today: the list prices with the pricing agreement applied, the VAT treatment and the current agreement.", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "priceList": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "currency": { "type": "string" }, "effectiveFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveTo": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] } }, "required": [ "id", "name", "currency", "effectiveFrom", "effectiveTo" ], "additionalProperties": false }, { "type": "null" } ] }, "agreement": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "effectiveFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "effectiveTo": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "discountPercent": { "type": [ "number", "null" ] } }, "required": [ "id", "name", "effectiveFrom", "effectiveTo", "discountPercent" ], "additionalProperties": false }, { "type": "null" } ] }, "vat": { "type": "object", "properties": { "treatment": { "type": "string", "enum": [ "NL_STANDARD", "EU_REVERSE_CHARGE", "NON_EU" ] }, "rate": { "type": "integer" } }, "required": [ "treatment", "rate" ], "additionalProperties": false }, "rules": { "type": "array", "items": { "type": "object", "properties": { "productId": { "type": "string" }, "productName": { "type": "string" }, "finish": { "type": [ "string", "null" ] }, "destination": { "type": [ "string", "null" ] }, "minQuantity": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "unitPriceCents": { "type": "integer" }, "source": { "type": "string", "enum": [ "list", "agreement" ] } }, "required": [ "productId", "productName", "finish", "destination", "minQuantity", "listUnitPriceCents", "unitPriceCents", "source" ], "additionalProperties": false } } }, "required": [ "priceList", "agreement", "vat", "rules" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/statements/{month}": { "get": { "operationId": "invoices.statement", "summary": "The usage statement of a month", "description": "Usage per product, finish, destination and run plus fees and adjustments for YYYY-MM; add format=csv for a CSV body (text/csv) with the lines.", "tags": [ "Billing" ], "x-rate-limit-class": "export", "parameters": [ { "name": "month", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "organisationId": { "type": "string" }, "month": { "type": "string", "pattern": "^\\d{4}-\\d{2}$" }, "periodFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "periodTo": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "billingMode": { "type": "string", "enum": [ "PREPAID", "TRIAL", "INVOICE" ] }, "currency": { "type": "string" }, "lines": { "type": "array", "items": { "type": "object", "properties": { "position": { "type": "integer" }, "kind": { "type": "string", "enum": [ "TOP_UP", "USAGE", "SUBSCRIPTION_FEE", "ADJUSTMENT", "CREDIT" ] }, "description": { "type": "string" }, "quantity": { "type": "integer" }, "unitPriceCents": { "type": "integer" }, "amountCents": { "type": "integer" }, "referenceType": { "type": [ "string", "null" ] }, "referenceId": { "type": [ "string", "null" ] } }, "required": [ "position", "kind", "description", "quantity", "unitPriceCents", "amountCents", "referenceType", "referenceId" ], "additionalProperties": false } }, "subtotalCents": { "type": "integer" }, "invoice": { "type": [ "string", "null" ] } }, "required": [ "organisationId", "month", "periodFrom", "periodTo", "billingMode", "currency", "lines", "subtotalCents", "invoice" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/summary": { "get": { "operationId": "billing.summary", "summary": "Billing summary", "description": "The billing mode and the figures in cents: balance, reserved for READY items, available (balance minus reserved), outstanding (INVOICE), the credit limit and headroom, the trial allowance and the low balance threshold.", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "organisationId": { "type": "string" }, "billingMode": { "type": "string", "enum": [ "PREPAID", "TRIAL", "INVOICE" ] }, "currency": { "type": "string" }, "balanceCents": { "type": "integer" }, "reservedCents": { "type": "integer" }, "availableCents": { "type": "integer" }, "outstandingCents": { "type": "integer" }, "creditLimitCents": { "type": "integer" }, "creditHeadroomCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "trial": { "anyOf": [ { "type": "object", "properties": { "itemsRemaining": { "type": "integer" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "itemsRemaining", "expiresAt", "active" ], "additionalProperties": false }, { "type": "null" } ] }, "lowBalanceThresholdCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lowBalanceNotifiedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "reconciledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "organisationId", "billingMode", "currency", "balanceCents", "reservedCents", "availableCents", "outstandingCents", "creditLimitCents", "creditHeadroomCents", "trial", "lowBalanceThresholdCents", "lowBalanceNotifiedAt", "reconciledAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/billing/top-ups": { "post": { "operationId": "billing.topUp", "summary": "Request a top-up", "description": "Creates a pending top-up for a prepaid or trial organisation and returns the payment with the instructions of the payment provider (bank transfer with a reference under the manual provider). The balance is credited once the payment is registered as received.", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "amountCents": { "type": "integer", "minimum": 500, "maximum": 100000000 } }, "required": [ "amountCents" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "payment": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "TOP_UP", "INVOICE_PAYMENT" ] }, "provider": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "COMPLETED", "CANCELLED" ] }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "method": { "anyOf": [ { "type": "string", "enum": [ "BANK_TRANSFER", "OTHER" ] }, { "type": "null" } ] }, "reference": { "type": "string" }, "externalReference": { "type": [ "string", "null" ] }, "paidAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "invoiceId": { "type": [ "string", "null" ] }, "ledgerEntryId": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] }, "requestedByType": { "type": "string", "enum": [ "USER", "API_KEY", "ADMIN", "SYSTEM" ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "provider", "status", "amountCents", "currency", "method", "reference", "externalReference", "paidAt", "invoiceId", "ledgerEntryId", "notes", "requestedByType", "completedAt", "cancelledAt", "createdAt" ], "additionalProperties": false }, "instructions": { "anyOf": [ { "type": "object", "properties": { "method": { "type": "string", "const": "BANK_TRANSFER" }, "beneficiary": { "type": "string" }, "iban": { "type": "string" }, "bic": { "type": [ "string", "null" ] }, "amountCents": { "type": "integer" }, "currency": { "type": "string" }, "reference": { "type": "string" }, "note": { "type": "string" } }, "required": [ "method", "beneficiary", "iban", "bic", "amountCents", "currency", "reference", "note" ], "additionalProperties": false }, { "type": "null" } ] }, "redirectUrl": { "type": [ "string", "null" ] } }, "required": [ "payment", "instructions", "redirectUrl" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.manage" } }, "/v1/dashboard": { "get": { "operationId": "analytics.dashboard", "summary": "The organisation dashboard", "description": "Next planned run per product group with the scheduled count, items needing attention, pending approvals, the billing figures, thirty-day counts, QR scan totals, the last twenty events and the onboarding checklist.", "tags": [ "Organisation" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "type": "object", "properties": { "productGroup": { "type": "string" }, "run": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "cutoffAt": { "type": "string", "format": "date-time" }, "handoverWeek": { "type": "string" }, "handoverMonday": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "id", "cutoffAt", "handoverWeek", "handoverMonday" ], "additionalProperties": false }, { "type": "null" } ] }, "expectedDeliveryFrom": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "scheduled": { "type": "integer" } }, "required": [ "productGroup", "run", "expectedDeliveryFrom", "scheduled" ], "additionalProperties": false } }, "needsAttention": { "type": "integer" }, "pendingApprovals": { "type": "integer" }, "scheduled": { "type": "integer" }, "sentLast30Days": { "type": "integer" }, "createdLast30Days": { "type": "integer" }, "scans": { "type": "integer" }, "billing": { "type": "object", "properties": { "billingMode": { "type": "string", "enum": [ "PREPAID", "TRIAL", "INVOICE" ] }, "availableCents": { "type": "integer" }, "balanceCents": { "type": "integer" }, "outstandingCents": { "type": "integer" }, "creditLimitCents": { "type": "integer" }, "creditUsagePercent": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "trial": { "anyOf": [ { "type": "object", "properties": { "itemsRemaining": { "type": "integer" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "itemsRemaining", "expiresAt", "active" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "billingMode", "availableCents", "balanceCents", "outstandingCents", "creditLimitCents", "creditUsagePercent", "trial" ], "additionalProperties": false }, "checklist": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "profile", "templatePublished", "sampleOrdered", "apiKeyOrIntegration", "postflowActive", "runParticipated" ] }, "done": { "type": "boolean" }, "link": { "type": "string" } }, "required": [ "key", "done", "link" ], "additionalProperties": false } }, "onboardingComplete": { "type": "boolean" }, "recentActivity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "payload": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "type", "createdAt", "payload" ], "additionalProperties": false } } }, "required": [ "runs", "needsAttention", "pendingApprovals", "scheduled", "sentLast30Days", "createdLast30Days", "scans", "billing", "checklist", "onboardingComplete", "recentActivity" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/events": { "get": { "operationId": "events.list", "summary": "Event feed", "description": "The organisation's events newest first in the webhook envelope (id, type, version, createdAt, organisationId, isTest, data) with a cursor, retained for 30 days; filter on type (comma separated) and a period. For polling integrations that do not receive webhooks.", "tags": [ "Webhooks" ], "parameters": [ { "name": "type", "in": "query", "required": false, "schema": { "allOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string", "maxLength": 60 }, "minItems": 1, "maxItems": 20 } ] } }, { "name": "from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "organisationId": { "type": "string" }, "isTest": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "type", "version", "createdAt", "organisationId", "isTest", "data" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/events/{id}": { "get": { "operationId": "events.get", "summary": "Get an event", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "organisationId": { "type": "string" }, "isTest": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "type", "version", "createdAt", "organisationId", "isTest", "data" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/exports": { "get": { "operationId": "exports.list", "summary": "List recent exports", "tags": [ "Exports" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "items", "suppressions", "templates" ] }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED", "EXPIRED" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "error": { "type": [ "string", "null" ] }, "downloadUrl": { "type": [ "string", "null" ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "status", "fileName", "contentType", "counts", "error", "downloadUrl", "expiresAt", "createdAt", "finishedAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "organisation.read" }, "post": { "operationId": "exports.request", "summary": "Request a data export", "description": "Items or the suppression list as CSV, templates as a zip with JSON documents and assets; poll until READY, then download within 24 hours (PRIV-003).", "tags": [ "Exports" ], "x-idempotent": true, "x-rate-limit-class": "export", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "items", "suppressions", "templates" ] } }, "required": [ "kind" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "items", "suppressions", "templates" ] }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED", "EXPIRED" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "error": { "type": [ "string", "null" ] }, "downloadUrl": { "type": [ "string", "null" ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "status", "fileName", "contentType", "counts", "error", "downloadUrl", "expiresAt", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "organisation.settings" } }, "/v1/exports/{id}": { "get": { "operationId": "exports.get", "summary": "Get an export with its download link", "tags": [ "Exports" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "items", "suppressions", "templates" ] }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED", "EXPIRED" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "error": { "type": [ "string", "null" ] }, "downloadUrl": { "type": [ "string", "null" ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "status", "fileName", "contentType", "counts", "error", "downloadUrl", "expiresAt", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "organisation.read" } }, "/v1/fonts": { "get": { "operationId": "uploads.fonts", "summary": "List organisation fonts", "tags": [ "Uploads" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "familyName": { "type": "string" }, "subfamilyName": { "type": "string" }, "postscriptName": { "type": "string" }, "weight": { "type": "integer" }, "italic": { "type": "boolean" }, "variable": { "type": "boolean" }, "format": { "type": "string", "enum": [ "ttf", "otf", "woff2" ] }, "sizeBytes": { "type": "integer" }, "glyphCount": { "type": "integer" }, "missingCharacters": { "type": "array", "items": { "type": "string" } }, "coverageComplete": { "type": "boolean" }, "licenceConfirmed": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "familyName", "subfamilyName", "postscriptName", "weight", "italic", "variable", "format", "sizeBytes", "glyphCount", "missingCharacters", "coverageComplete", "licenceConfirmed", "url", "createdAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/fonts/{id}": { "get": { "operationId": "uploads.font", "summary": "Get an organisation font", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "familyName": { "type": "string" }, "subfamilyName": { "type": "string" }, "postscriptName": { "type": "string" }, "weight": { "type": "integer" }, "italic": { "type": "boolean" }, "variable": { "type": "boolean" }, "format": { "type": "string", "enum": [ "ttf", "otf", "woff2" ] }, "sizeBytes": { "type": "integer" }, "glyphCount": { "type": "integer" }, "missingCharacters": { "type": "array", "items": { "type": "string" } }, "coverageComplete": { "type": "boolean" }, "licenceConfirmed": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "familyName", "subfamilyName", "postscriptName", "weight", "italic", "variable", "format", "sizeBytes", "glyphCount", "missingCharacters", "coverageComplete", "licenceConfirmed", "url", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" }, "delete": { "operationId": "uploads.deleteFont", "summary": "Delete an organisation font", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/integrations/apps": { "get": { "operationId": "integrations.apps", "summary": "Integration apps", "description": "The registry as it applies to the organisation: apps with their status (ACTIVE to install, COMING_SOON, NOT_IN_PLAN when another plan offers it, WITHDRAWN when no new installations are possible but the organisation has one), capabilities and configuration fields.", "tags": [ "Integrations" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "COMING_SOON", "NOT_IN_PLAN", "WITHDRAWN" ] }, "capabilities": { "type": "array", "items": { "type": "string", "enum": [ "outbound", "inbound" ] } }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "type": { "type": "string", "enum": [ "url", "string", "boolean", "select" ] }, "required": { "type": "boolean" }, "secret": { "type": "boolean" }, "options": { "type": "array", "items": { "type": "string" } }, "hint": { "type": "string" } }, "required": [ "key", "label", "type" ], "additionalProperties": false } } }, "required": [ "key", "name", "description", "status", "capabilities", "fields" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.read" } }, "/v1/integrations/apps/{appKey}/installations": { "post": { "operationId": "integrations.install", "summary": "Install an integration", "description": "Validates the configuration against the app, creates a dedicated live API key (scoped to Postflows, items, templates and prices) and, when a writeback is configured, a dedicated webhook endpoint for item events; both secrets are returned once. Credentials are stored sealed.", "tags": [ "Integrations" ], "parameters": [ { "name": "appKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "config": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "properties": { "clientSecret": { "type": "string", "minLength": 3, "maxLength": 500 } }, "additionalProperties": false } }, "required": [ "config" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "installation": { "type": "object", "properties": { "id": { "type": "string" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "properties": { "instanceUrl": { "type": "string" }, "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "writebackUrl": { "type": "string" }, "clientId": { "type": "string" }, "mirrorAllItems": { "type": "boolean" } }, "required": [ "instanceUrl", "writebackMethod", "mirrorAllItems" ], "additionalProperties": false }, "hasCredentials": { "type": "boolean" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "ERROR", "DISABLED" ] }, "lastError": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "webhookEndpointId": { "type": [ "string", "null" ] }, "lastActivityAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "healthCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appKey", "name", "config", "hasCredentials", "status", "lastError", "apiKeyId", "webhookEndpointId", "lastActivityAt", "healthCheckedAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "apiKey": { "type": "object", "properties": { "id": { "type": "string" }, "prefix": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "prefix", "secret" ], "additionalProperties": false }, "webhook": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "url", "secret" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "installation", "apiKey", "webhook" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.manage" } }, "/v1/integrations/installations": { "get": { "operationId": "integrations.list", "summary": "List installations", "tags": [ "Integrations" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "properties": { "instanceUrl": { "type": "string" }, "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "writebackUrl": { "type": "string" }, "clientId": { "type": "string" }, "mirrorAllItems": { "type": "boolean" } }, "required": [ "instanceUrl", "writebackMethod", "mirrorAllItems" ], "additionalProperties": false }, "hasCredentials": { "type": "boolean" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "ERROR", "DISABLED" ] }, "lastError": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "webhookEndpointId": { "type": [ "string", "null" ] }, "lastActivityAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "healthCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appKey", "name", "config", "hasCredentials", "status", "lastError", "apiKeyId", "webhookEndpointId", "lastActivityAt", "healthCheckedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.read" } }, "/v1/integrations/installations/{id}": { "get": { "operationId": "integrations.get", "summary": "Get an installation with its activity", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "properties": { "instanceUrl": { "type": "string" }, "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "writebackUrl": { "type": "string" }, "clientId": { "type": "string" }, "mirrorAllItems": { "type": "boolean" } }, "required": [ "instanceUrl", "writebackMethod", "mirrorAllItems" ], "additionalProperties": false }, "hasCredentials": { "type": "boolean" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "ERROR", "DISABLED" ] }, "lastError": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "webhookEndpointId": { "type": [ "string", "null" ] }, "lastActivityAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "healthCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "activity": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "INSTALLED", "CONFIGURED", "ENABLED", "DISABLED", "REMOVED", "ERROR", "HEALTH", "OUTBOUND", "INBOUND" ] }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "fields": { "type": "array", "items": { "type": "string" } }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string", "enum": [ "api_key", "writeback" ] }, "ok": { "type": "boolean" }, "detail": { "type": [ "string", "null" ] } }, "required": [ "check", "ok", "detail" ], "additionalProperties": false } }, "error": { "type": "string" }, "status": { "type": "integer" }, "url": { "type": [ "string", "null" ] } }, "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "message", "data", "createdAt" ], "additionalProperties": false } } }, "required": [ "id", "appKey", "name", "config", "hasCredentials", "status", "lastError", "apiKeyId", "webhookEndpointId", "lastActivityAt", "healthCheckedAt", "createdAt", "updatedAt", "activity" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.read" }, "patch": { "operationId": "integrations.patch", "summary": "Update an installation", "description": "Name, configuration (merged and re-validated; the writeback endpoint follows) and credentials. When the update creates the writeback endpoint, webhook carries its signing secret once.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "config": { "type": "object", "additionalProperties": {} }, "credentials": { "type": "object", "properties": { "clientSecret": { "type": "string", "minLength": 3, "maxLength": 500 } }, "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "properties": { "instanceUrl": { "type": "string" }, "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "writebackUrl": { "type": "string" }, "clientId": { "type": "string" }, "mirrorAllItems": { "type": "boolean" } }, "required": [ "instanceUrl", "writebackMethod", "mirrorAllItems" ], "additionalProperties": false }, "hasCredentials": { "type": "boolean" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "ERROR", "DISABLED" ] }, "lastError": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "webhookEndpointId": { "type": [ "string", "null" ] }, "lastActivityAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "healthCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "webhook": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "secret": { "type": "string" } }, "required": [ "id", "url", "secret" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "appKey", "name", "config", "hasCredentials", "status", "lastError", "apiKeyId", "webhookEndpointId", "lastActivityAt", "healthCheckedAt", "createdAt", "updatedAt", "webhook" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.manage" }, "delete": { "operationId": "integrations.remove", "summary": "Remove an installation", "description": "Revokes the dedicated key, deletes the webhook endpoint and the installation.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.manage" } }, "/v1/integrations/installations/{id}/disable": { "post": { "operationId": "integrations.disable", "summary": "Disable an installation", "description": "Items created with its key are refused with integration_disabled; its webhook endpoint pauses.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "properties": { "instanceUrl": { "type": "string" }, "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "writebackUrl": { "type": "string" }, "clientId": { "type": "string" }, "mirrorAllItems": { "type": "boolean" } }, "required": [ "instanceUrl", "writebackMethod", "mirrorAllItems" ], "additionalProperties": false }, "hasCredentials": { "type": "boolean" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "ERROR", "DISABLED" ] }, "lastError": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "webhookEndpointId": { "type": [ "string", "null" ] }, "lastActivityAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "healthCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appKey", "name", "config", "hasCredentials", "status", "lastError", "apiKeyId", "webhookEndpointId", "lastActivityAt", "healthCheckedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.manage" } }, "/v1/integrations/installations/{id}/enable": { "post": { "operationId": "integrations.enable", "summary": "Enable an installation", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "properties": { "instanceUrl": { "type": "string" }, "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "writebackUrl": { "type": "string" }, "clientId": { "type": "string" }, "mirrorAllItems": { "type": "boolean" } }, "required": [ "instanceUrl", "writebackMethod", "mirrorAllItems" ], "additionalProperties": false }, "hasCredentials": { "type": "boolean" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "ERROR", "DISABLED" ] }, "lastError": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "webhookEndpointId": { "type": [ "string", "null" ] }, "lastActivityAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "healthCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "appKey", "name", "config", "hasCredentials", "status", "lastError", "apiKeyId", "webhookEndpointId", "lastActivityAt", "healthCheckedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.manage" } }, "/v1/integrations/installations/{id}/health": { "post": { "operationId": "integrations.health", "summary": "Run the health check", "description": "Checks the dedicated key and sends a test event to the writeback endpoint; sets the status to ACTIVE or ERROR.", "tags": [ "Integrations" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "appKey": { "type": "string" }, "name": { "type": "string" }, "config": { "type": "object", "properties": { "instanceUrl": { "type": "string" }, "writebackMethod": { "type": "string", "enum": [ "NONE", "CONNECTED_APP", "SITE_GUEST" ] }, "writebackUrl": { "type": "string" }, "clientId": { "type": "string" }, "mirrorAllItems": { "type": "boolean" } }, "required": [ "instanceUrl", "writebackMethod", "mirrorAllItems" ], "additionalProperties": false }, "hasCredentials": { "type": "boolean" }, "status": { "type": "string", "enum": [ "PENDING", "ACTIVE", "ERROR", "DISABLED" ] }, "lastError": { "type": [ "string", "null" ] }, "apiKeyId": { "type": [ "string", "null" ] }, "webhookEndpointId": { "type": [ "string", "null" ] }, "lastActivityAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "healthCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "check": { "type": "string", "enum": [ "api_key", "writeback" ] }, "ok": { "type": "boolean" }, "detail": { "type": [ "string", "null" ] } }, "required": [ "check", "ok", "detail" ], "additionalProperties": false } } }, "required": [ "id", "appKey", "name", "config", "hasCredentials", "status", "lastError", "apiKeyId", "webhookEndpointId", "lastActivityAt", "healthCheckedAt", "createdAt", "updatedAt", "checks" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "integrations.manage" } }, "/v1/items": { "get": { "operationId": "items.list", "summary": "List items", "description": "Cursor paged (API-005); test keys see test items only.", "tags": [ "Items" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor of the previous page (same sort and filters).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma separated, prefix - for descending; fields: createdAt, sendDate. Default -createdAt.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "include=total adds totalCount.", "schema": { "type": "string", "enum": [ "total" ] } }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] } }, { "name": "filter[status][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[status][ne]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] } }, { "name": "filter[postflowId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[postflowId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[postbatchId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[postbatchId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[integrationInstallationId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[integrationInstallationId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[isTest]", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter[isSample]", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter[externalId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[externalId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[createdAt][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][null]", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter[search][contains]", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "type": "integer" } }, "required": [ "data", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/items/{id}": { "get": { "operationId": "items.get", "summary": "Get an item", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "patch": { "operationId": "items.repair", "summary": "Repair or edit an item", "description": "A NEEDS_ATTENTION item takes a new recipient and variables, is validated again and re-enters the queue (ITEM-004). A HELD item accepts a new send date, external id and metadata. Later statuses cannot be edited.", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "addressLine1": { "type": "string", "maxLength": 200 }, "addressLine2": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 120 }, "country": { "type": "string", "maxLength": 40 } }, "additionalProperties": false }, "variables": { "type": "object", "additionalProperties": {} }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "The item cannot be edited in its status (invalid_item_transition)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.write" } }, "/v1/items/{id}/cancel": { "post": { "operationId": "items.cancel", "summary": "Cancel an item", "description": "Allowed until the run cutoff (HELD, PENDING_APPROVAL, READY, NEEDS_ATTENTION); a reservation is released (ITEM-005).", "tags": [ "Items" ], "x-idempotent": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed, or the Idempotency-Key was used with another body (idempotency_key_reused)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.write" } }, "/v1/items/{id}/events": { "get": { "operationId": "items.events", "summary": "List the status history of an item", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "fromStatus": { "anyOf": [ { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, { "type": "null" } ] }, "toStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "actorType": { "type": "string", "enum": [ "USER", "API_KEY", "ADMIN", "SYSTEM", "PARTNER" ] }, "reason": { "type": [ "string", "null" ] }, "payload": { "type": "object", "properties": {}, "additionalProperties": true }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "fromStatus", "toStatus", "actorType", "reason", "payload", "createdAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/items/{id}/pdf": { "get": { "operationId": "items.pdf", "summary": "Production PDF of an item", "description": "A signed URL valid for ten minutes once the item was rendered for its run; gone after anonymisation (DEC-0091).", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "string" }, "url": { "type": "string" }, "expiresInSeconds": { "type": "integer" } }, "required": [ "itemId", "url", "expiresInSeconds" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/items/{id}/preview": { "get": { "operationId": "items.preview", "summary": "Preview images of an item", "description": "Renders the item with its template version, recipient and variables through a render request; poll until READY for the signed image URLs (ITEM-007).", "tags": [ "Items" ], "x-rate-limit-class": "preview", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "side", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,30}$" } }, { "name": "dpi", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 36, "maximum": 300, "default": 150 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "string" }, "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "type": "object", "properties": { "variables": { "type": "object", "properties": {}, "additionalProperties": true }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "side": { "type": [ "string", "null" ] }, "dpi": { "type": "integer" }, "qrShortUrl": { "type": [ "string", "null" ] } }, "required": [ "variables", "recipient", "side", "dpi", "qrShortUrl" ], "additionalProperties": false }, "urls": { "type": "object", "additionalProperties": { "type": "string" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "itemId", "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/items/{id}/scans": { "get": { "operationId": "items.scans", "summary": "List the QR scans of an item", "description": "Scan events of the item with a trackable QR code, newest first (up to 500): timestamp, user agent class and coarse country. Bot scans are listed but not counted. Events are removed at anonymisation; the counters on the item remain.", "tags": [ "Items" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "scannedAt": { "type": "string", "format": "date-time" }, "uaClass": { "type": "string", "enum": [ "mobile", "desktop", "bot", "unknown" ] }, "country": { "type": [ "string", "null" ] } }, "required": [ "id", "scannedAt", "uaClass", "country" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/items/bulk-repair": { "post": { "operationId": "items.bulkRepair", "summary": "Repair several items with the same patch", "description": "Applies one patch to up to 500 items (ITEM-004 bulk edit); the result lists each item with its new status or the error code.", "tags": [ "Items" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 500 }, "patch": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "addressLine1": { "type": "string", "maxLength": 200 }, "addressLine2": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 120 }, "country": { "type": "string", "maxLength": 40 } }, "additionalProperties": false }, "variables": { "type": "object", "additionalProperties": {} }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "type": "object", "additionalProperties": {} }, { "type": "null" } ] } }, "additionalProperties": false } }, "required": [ "itemIds", "patch" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, { "type": "null" } ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "error": { "type": "string" } }, "required": [ "id", "status" ], "additionalProperties": false } }, "repaired": { "type": "integer" } }, "required": [ "results", "repaired" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.write" } }, "/v1/jobs/{id}": { "get": { "operationId": "renders.getJob", "summary": "Get a render job with its signed PDF URL", "tags": [ "Renders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "anyOf": [ { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "side": { "type": [ "string", "null" ] }, "dpi": { "type": "integer" }, "qrShortUrl": { "type": [ "string", "null" ] } }, "required": [ "variables", "recipient", "side", "dpi" ], "additionalProperties": false }, { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false } ] }, "urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/media/delete": { "post": { "operationId": "media.bulkDelete", "summary": "Delete unused images and fonts in bulk", "tags": [ "Media" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assetIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "default": [] }, "fontIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "maxItems": 500, "default": [] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "array", "items": { "type": "string" } }, "refused": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "reason": { "type": "string" }, "usages": { "type": "array", "items": { "type": "object", "properties": { "templateId": { "type": "string" }, "templateName": { "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "archived": { "type": "boolean" } }, "required": [ "templateId", "templateName", "version", "archived" ], "additionalProperties": false } } }, "required": [ "id", "reason", "usages" ], "additionalProperties": false } } }, "required": [ "deleted", "refused" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/media/fonts": { "get": { "operationId": "media.fonts", "summary": "Fonts with where they are used", "tags": [ "Media" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "familyName": { "type": "string" }, "subfamilyName": { "type": "string" }, "postscriptName": { "type": "string" }, "weight": { "type": "integer" }, "italic": { "type": "boolean" }, "variable": { "type": "boolean" }, "format": { "type": "string", "enum": [ "ttf", "otf", "woff2" ] }, "sizeBytes": { "type": "integer" }, "glyphCount": { "type": "integer" }, "missingCharacters": { "type": "array", "items": { "type": "string" } }, "coverageComplete": { "type": "boolean" }, "licenceConfirmed": { "type": "boolean" }, "url": { "type": "string", "format": "uri" }, "createdAt": { "type": "string", "format": "date-time" }, "usages": { "type": "array", "items": { "type": "object", "properties": { "templateId": { "type": "string" }, "templateName": { "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "archived": { "type": "boolean" } }, "required": [ "templateId", "templateName", "version", "archived" ], "additionalProperties": false } } }, "required": [ "id", "familyName", "subfamilyName", "postscriptName", "weight", "italic", "variable", "format", "sizeBytes", "glyphCount", "missingCharacters", "coverageComplete", "licenceConfirmed", "url", "createdAt", "usages" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/media/images": { "get": { "operationId": "media.images", "summary": "Images with their size and where they are used", "tags": [ "Media" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "format": { "type": "string", "enum": [ "jpeg", "png" ] }, "widthPx": { "type": "integer" }, "heightPx": { "type": "integer" }, "hasAlpha": { "type": "boolean" }, "colourProfile": { "type": "string" }, "sizeBytes": { "type": "integer" }, "urls": { "type": "object", "properties": { "master": { "type": "string", "format": "uri" }, "thumb": { "type": "string", "format": "uri" } }, "required": [ "master", "thumb" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "storedBytes": { "type": "integer" }, "usages": { "type": "array", "items": { "type": "object", "properties": { "templateId": { "type": "string" }, "templateName": { "type": "string" }, "version": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "archived": { "type": "boolean" } }, "required": [ "templateId", "templateName", "version", "archived" ], "additionalProperties": false } } }, "required": [ "id", "name", "format", "widthPx", "heightPx", "hasAlpha", "colourProfile", "sizeBytes", "urls", "createdAt", "storedBytes", "usages" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/media/storage": { "get": { "operationId": "media.storage", "summary": "Storage use against the plan, with a breakdown", "tags": [ "Media" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "usedBytes": { "type": "integer" }, "limitBytes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "fonts": { "type": "object", "properties": { "used": { "type": "integer" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "used", "max" ], "additionalProperties": false }, "breakdown": { "type": "object", "properties": { "images": { "type": "object", "properties": { "bytes": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "bytes", "count" ], "additionalProperties": false }, "fonts": { "type": "object", "properties": { "bytes": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "bytes", "count" ], "additionalProperties": false }, "csvImports": { "type": "object", "properties": { "bytes": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "bytes", "count" ], "additionalProperties": false }, "exports": { "type": "object", "properties": { "bytes": { "type": "integer" }, "count": { "type": "integer" } }, "required": [ "bytes", "count" ], "additionalProperties": false } }, "required": [ "images", "fonts", "csvImports", "exports" ], "additionalProperties": false }, "unused": { "type": "object", "properties": { "count": { "type": "integer" }, "bytes": { "type": "integer" } }, "required": [ "count", "bytes" ], "additionalProperties": false }, "largest": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "font", "csv", "export" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "sizeBytes": { "type": "integer" }, "inUse": { "type": "boolean" } }, "required": [ "kind", "id", "name", "sizeBytes", "inUse" ], "additionalProperties": false } }, "temporary": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "csv", "export" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "sizeBytes": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "context": { "type": "string" } }, "required": [ "kind", "id", "name", "sizeBytes", "createdAt", "context" ], "additionalProperties": false } } }, "required": [ "usedBytes", "limitBytes", "fonts", "breakdown", "unused", "largest", "temporary" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/openapi.json": { "get": { "operationId": "openApi.document", "summary": "OpenAPI document of this API", "tags": [ "Meta" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "openapi": { "type": "string" }, "info": { "type": "object", "properties": { "title": { "type": "string" }, "version": { "type": "string" } }, "required": [ "title", "version" ], "additionalProperties": true }, "paths": { "type": "object", "properties": {}, "additionalProperties": true }, "components": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "openapi", "info", "paths", "components" ], "additionalProperties": true } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/v1/organisation": { "get": { "operationId": "organisations.organisation", "summary": "Get the organisation profile and settings", "tags": [ "Organisations" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "locale": { "type": "string", "enum": [ "nl", "en" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "SUSPENDED", "PENDING_DELETION" ] }, "billingMode": { "type": "string", "enum": [ "PREPAID", "TRIAL", "INVOICE" ] }, "settings": { "type": "object", "properties": { "retentionDays": { "type": "integer" }, "requirePostflowApproval": { "type": "boolean" }, "requireMfa": { "type": "boolean" }, "postbatchApprovalThreshold": { "type": "integer" }, "lowBalanceThresholdCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "retentionDays", "requirePostflowApproval", "requireMfa", "postbatchApprovalThreshold", "lowBalanceThresholdCents" ], "additionalProperties": false }, "admin": { "type": "object", "properties": { "priority": { "type": "integer" }, "creditLimitCents": { "type": "integer" }, "paymentTermDays": { "type": "integer" }, "trialItemsRemaining": { "type": "integer" }, "trialExpiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "rateLimits": { "anyOf": [ { "type": "object", "properties": { "general": { "type": "integer" }, "itemCreate": { "type": "integer" }, "preview": { "type": "integer" }, "upload": { "type": "integer" }, "export": { "type": "integer" }, "invite": { "type": "integer" }, "public": { "type": "integer" } }, "additionalProperties": false }, { "type": "null" } ] }, "effectiveRateLimits": { "type": "object", "properties": { "general": { "type": "integer" }, "itemCreate": { "type": "integer" }, "preview": { "type": "integer" }, "upload": { "type": "integer" }, "export": { "type": "integer" }, "invite": { "type": "integer" }, "public": { "type": "integer" } }, "required": [ "general", "itemCreate", "preview", "upload", "export", "invite", "public" ], "additionalProperties": false } }, "required": [ "priority", "creditLimitCents", "paymentTermDays", "trialItemsRemaining", "trialExpiresAt", "rateLimits", "effectiveRateLimits" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" }, "billingProfile": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "legalName": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "invoiceEmail": { "type": "string" }, "vatNumber": { "type": [ "string", "null" ] }, "vatTreatment": { "type": "string", "enum": [ "NL_STANDARD", "EU_REVERSE_CHARGE", "NON_EU" ] }, "viesStatus": { "type": "string", "enum": [ "UNCHECKED", "VALID", "INVALID", "UNAVAILABLE" ] }, "viesCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "viesName": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organisationId", "legalName", "addressLine1", "addressLine2", "postalCode", "city", "country", "invoiceEmail", "vatNumber", "vatTreatment", "viesStatus", "viesCheckedAt", "viesName", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "role": { "anyOf": [ { "type": "string", "enum": [ "OWNER", "ADMIN", "EDITOR", "APPROVER", "DEVELOPER", "VIEWER" ] }, { "type": "null" } ] }, "permissions": { "type": "array", "items": { "type": "string", "enum": [ "organisation.manage", "organisation.settings", "organisation.read", "members.manage", "billing.read", "billing.manage", "templates.read", "templates.write", "postflows.read", "postflows.write", "postbatches.write", "postbatches.approve", "items.read", "items.write", "items.approve", "suppressions.manage", "apikeys.manage", "webhooks.manage", "integrations.manage", "integrations.read", "support_sessions.read" ] } } }, "required": [ "id", "name", "slug", "locale", "status", "billingMode", "settings", "admin", "createdAt", "billingProfile", "role", "permissions" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/organisation/billing-profile": { "get": { "operationId": "organisations.billingProfile", "summary": "Get the billing profile", "tags": [ "Organisations" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "legalName": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "invoiceEmail": { "type": "string" }, "vatNumber": { "type": [ "string", "null" ] }, "vatTreatment": { "type": "string", "enum": [ "NL_STANDARD", "EU_REVERSE_CHARGE", "NON_EU" ] }, "viesStatus": { "type": "string", "enum": [ "UNCHECKED", "VALID", "INVALID", "UNAVAILABLE" ] }, "viesCheckedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "viesName": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "organisationId", "legalName", "addressLine1", "addressLine2", "postalCode", "city", "country", "invoiceEmail", "vatNumber", "vatTreatment", "viesStatus", "viesCheckedAt", "viesName", "createdAt", "updatedAt" ], "additionalProperties": false }, { "type": "null" } ] } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/organisation/plan": { "get": { "operationId": "plan.mine", "summary": "The organisation plan and its usage", "description": "The subscribed plan, the effective entitlements (plan merged with any overrides) and the usage against them: Postflows in use, items released this month, webhook endpoints, fonts and storage. Limits answer with postflow_limit_reached, product_not_entitled, feature_not_entitled or allowance_exceeded at the point of use.", "tags": [ "Organisation" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "monthlyFeeCents": { "type": "integer" }, "currency": { "type": "string" } }, "required": [ "id", "key", "name", "monthlyFeeCents", "currency" ], "additionalProperties": false }, { "type": "null" } ] }, "subscription": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "planId": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "ENDED", "CANCELLED" ] }, "startsAt": { "type": "string", "format": "date-time" }, "endsAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "planId", "status", "startsAt", "endsAt", "createdAt" ], "additionalProperties": false }, { "type": "null" } ] }, "entitlements": { "type": "object", "properties": { "maxPostflows": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "monthlyItemAllowance": { "type": "object", "properties": { "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "hardCap": { "type": "boolean" } }, "required": [ "limit", "hardCap" ], "additionalProperties": false }, "enabledProductIds": { "anyOf": [ { "type": "string", "const": "all" }, { "type": "array", "items": { "type": "string" } } ] }, "maxStorageMb": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxFonts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxImportRows": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWebhookEndpoints": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "features": { "type": "array", "items": { "type": "string", "enum": [ "qrTracking", "samples", "apiAccess", "runSchedule" ] } } }, "required": [ "maxPostflows", "monthlyItemAllowance", "enabledProductIds", "maxStorageMb", "maxFonts", "maxImportRows", "maxWebhookEndpoints", "features" ], "additionalProperties": false }, "usage": { "type": "object", "properties": { "postflows": { "type": "object", "properties": { "used": { "type": "integer" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "used", "max" ], "additionalProperties": false }, "itemsThisMonth": { "type": "object", "properties": { "used": { "type": "integer" }, "limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "hardCap": { "type": "boolean" }, "periodStart": { "type": "string", "format": "date-time" } }, "required": [ "used", "limit", "hardCap", "periodStart" ], "additionalProperties": false }, "webhookEndpoints": { "type": "object", "properties": { "used": { "type": "integer" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "used", "max" ], "additionalProperties": false }, "fonts": { "type": "object", "properties": { "used": { "type": "integer" }, "max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "used", "max" ], "additionalProperties": false }, "storage": { "type": "object", "properties": { "usedBytes": { "type": "integer" }, "maxMb": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "usedBytes", "maxMb" ], "additionalProperties": false } }, "required": [ "postflows", "itemsThisMonth", "webhookEndpoints", "fonts", "storage" ], "additionalProperties": false } }, "required": [ "plan", "subscription", "entitlements", "usage" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/organisation/support-sessions": { "get": { "operationId": "organisationSupport.list", "summary": "The support sessions on this organisation", "description": "Current and past sessions PostBuddy staff opened on the organisation (SUPPORT-002), newest first.", "tags": [ "Organisation" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "adminName": { "type": "string" }, "adminEmail": { "type": "string" }, "reason": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedBy": { "anyOf": [ { "type": "string", "enum": [ "ADMIN", "EXPIRY", "ORGANISATION" ] }, { "type": "null" } ] }, "exchangedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "blockedCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "ACTIVE", "ENDED" ] }, "remainingSeconds": { "type": "integer" } }, "required": [ "id", "organisationId", "adminName", "adminEmail", "reason", "startedAt", "expiresAt", "endedAt", "endedBy", "exchangedAt", "blockedCount", "status", "remainingSeconds" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "support_sessions.read" } }, "/v1/organisation/support-sessions/{id}/end": { "post": { "operationId": "organisationSupport.end", "summary": "End a support session on this organisation", "tags": [ "Organisation" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "adminName": { "type": "string" }, "adminEmail": { "type": "string" }, "reason": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedBy": { "anyOf": [ { "type": "string", "enum": [ "ADMIN", "EXPIRY", "ORGANISATION" ] }, { "type": "null" } ] }, "exchangedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "blockedCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "ACTIVE", "ENDED" ] }, "remainingSeconds": { "type": "integer" } }, "required": [ "id", "organisationId", "adminName", "adminEmail", "reason", "startedAt", "expiresAt", "endedAt", "endedBy", "exchangedAt", "blockedCount", "status", "remainingSeconds" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "organisation.manage" } }, "/v1/ping": { "get": { "operationId": "ping.ping", "summary": "Ping", "tags": [ "Meta" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "time": { "type": "string", "format": "date-time" } }, "required": [ "ok", "time" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/v1/platform-assets": { "get": { "operationId": "platformAssets.byIds", "summary": "Get platform images by id", "description": "The display renditions of platform images that a base template placed in a document (comma-separated ids, at most 100). Platform images are never listed with the organisation assets.", "tags": [ "PlatformAssets" ], "parameters": [ { "name": "ids", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 4000 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "format": { "type": "string", "enum": [ "jpeg", "png" ] }, "widthPx": { "type": "integer" }, "heightPx": { "type": "integer" }, "hasAlpha": { "type": "boolean" }, "urls": { "type": "object", "properties": { "display": { "type": "string" }, "thumb": { "type": "string" } }, "required": [ "display", "thumb" ], "additionalProperties": false } }, "required": [ "id", "name", "format", "widthPx", "heightPx", "hasAlpha", "urls" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/postbatches": { "get": { "operationId": "postbatches.list", "summary": "List Postbatches", "description": "Cursor paged (API-005) with the counts per item status; filter on status, template, campaign, created date and a name search.", "tags": [ "Postbatches" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor of the previous page (same sort and filters).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma separated, prefix - for descending; fields: createdAt, updatedAt, name. Default -createdAt.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "include=total adds totalCount.", "schema": { "type": "string", "enum": [ "total" ] } }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] } }, { "name": "filter[status][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[status][ne]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] } }, { "name": "filter[templateId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[templateId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[campaignId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[campaignId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[createdAt][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[search][contains]", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "type": "integer" } }, "required": [ "data", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "post": { "operationId": "postbatches.create", "summary": "Create a Postbatch", "description": "A Postbatch starts in DRAFT with a published template version, the finish and the destination; the product follows from the template. Upload the CSV next.", "tags": [ "Postbatches" ], "x-idempotent": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "campaignId": { "type": "string", "minLength": 1, "maxLength": 80 }, "advertisingCategory": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "templateVersionId": { "type": "string", "minLength": 1, "maxLength": 40 }, "finish": { "type": "string", "minLength": 1, "maxLength": 40 }, "destination": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "name", "templateVersionId", "finish", "destination" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}": { "get": { "operationId": "postbatches.get", "summary": "Get a Postbatch", "description": "With the counts per item status.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "patch": { "operationId": "postbatches.patch", "summary": "Rename a Postbatch or change its campaign", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 2, "maxLength": 120 }, "campaignId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] }, "advertisingCategory": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/approve": { "post": { "operationId": "postbatches.approve", "summary": "Approve a Postbatch", "description": "Pins the template version, locks the quote in a price snapshot, reserves the balance or checks the credit for the whole quote, and moves every valid item to READY for the next planned run or a later planned run of the product group (targetRunId). Items that need attention are skipped only with skipInvalid.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetRunId": { "type": "string", "minLength": 1, "maxLength": 40 }, "skipInvalid": { "type": "boolean", "default": false } }, "additionalProperties": false, "default": { "skipInvalid": false } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.approve" } }, "/v1/postbatches/{id}/cancel": { "post": { "operationId": "postbatches.cancel", "summary": "Cancel a Postbatch", "description": "Allowed in DRAFT, IMPORTING, VALIDATED, PENDING_APPROVAL and APPROVED: the open items are cancelled and their reservations released; answers invalid_postbatch_transition afterwards.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/import": { "get": { "operationId": "postbatches.getImport", "summary": "Import status", "description": "The latest import with its status (UPLOADED, PARSING, PARSED, MAPPED, PROCESSING, DONE, FAILED, CANCELLED), encoding, delimiter, headers, sample rows, row count, the proposed and confirmed mapping with its issues, the processing counts and errors.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "postbatchId": { "type": "string" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "UPLOADED", "PARSING", "PARSED", "MAPPED", "PROCESSING", "DONE", "FAILED", "CANCELLED" ] }, "encoding": { "type": [ "string", "null" ] }, "delimiter": { "type": [ "string", "null" ] }, "headers": { "type": "array", "items": { "type": "string" } }, "sampleRows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "rowCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "malformedRows": { "type": "array", "items": { "type": "integer" } }, "targets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "recipient", "variable" ] } }, "required": [ "name", "required", "kind" ], "additionalProperties": false } }, "proposedMapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "mappingSource": { "type": [ "string", "null" ] }, "mapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unknown_target", "unknown_column", "unmapped_required", "unused_column", "empty_expression" ] }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "target": { "type": "string" }, "column": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "rowCounts": { "type": "object", "additionalProperties": { "type": "integer" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "line": { "type": "integer" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "parsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "postbatchId", "uploadId", "status", "encoding", "delimiter", "headers", "sampleRows", "rowCount", "malformedRows", "targets", "proposedMapping", "mappingSource", "mapping", "issues", "rowCounts", "errors", "parsedAt", "startedAt", "finishedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "post": { "operationId": "postbatches.startImport", "summary": "Upload the CSV of a Postbatch", "description": "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.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1, "maxLength": 40 }, "mapping": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } } }, "required": [ "uploadId" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "postbatchId": { "type": "string" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "UPLOADED", "PARSING", "PARSED", "MAPPED", "PROCESSING", "DONE", "FAILED", "CANCELLED" ] }, "encoding": { "type": [ "string", "null" ] }, "delimiter": { "type": [ "string", "null" ] }, "headers": { "type": "array", "items": { "type": "string" } }, "sampleRows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "rowCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "malformedRows": { "type": "array", "items": { "type": "integer" } }, "targets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "recipient", "variable" ] } }, "required": [ "name", "required", "kind" ], "additionalProperties": false } }, "proposedMapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "mappingSource": { "type": [ "string", "null" ] }, "mapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unknown_target", "unknown_column", "unmapped_required", "unused_column", "empty_expression" ] }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "target": { "type": "string" }, "column": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "rowCounts": { "type": "object", "additionalProperties": { "type": "integer" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "line": { "type": "integer" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "parsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "postbatchId", "uploadId", "status", "encoding", "delimiter", "headers", "sampleRows", "rowCount", "malformedRows", "targets", "proposedMapping", "mappingSource", "mapping", "issues", "rowCounts", "errors", "parsedAt", "startedAt", "finishedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/import/cancel": { "post": { "operationId": "postbatches.cancelImport", "summary": "Cancel the import", "description": "Before processing; the Postbatch returns to DRAFT.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "postbatchId": { "type": "string" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "UPLOADED", "PARSING", "PARSED", "MAPPED", "PROCESSING", "DONE", "FAILED", "CANCELLED" ] }, "encoding": { "type": [ "string", "null" ] }, "delimiter": { "type": [ "string", "null" ] }, "headers": { "type": "array", "items": { "type": "string" } }, "sampleRows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "rowCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "malformedRows": { "type": "array", "items": { "type": "integer" } }, "targets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "recipient", "variable" ] } }, "required": [ "name", "required", "kind" ], "additionalProperties": false } }, "proposedMapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "mappingSource": { "type": [ "string", "null" ] }, "mapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unknown_target", "unknown_column", "unmapped_required", "unused_column", "empty_expression" ] }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "target": { "type": "string" }, "column": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "rowCounts": { "type": "object", "additionalProperties": { "type": "integer" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "line": { "type": "integer" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "parsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "postbatchId", "uploadId", "status", "encoding", "delimiter", "headers", "sampleRows", "rowCount", "malformedRows", "targets", "proposedMapping", "mappingSource", "mapping", "issues", "rowCounts", "errors", "parsedAt", "startedAt", "finishedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/import/mapping": { "put": { "operationId": "postbatches.setMapping", "summary": "Confirm the mapping", "description": "Every required target needs an expression of static text and {{column}} references; unknown columns and targets are refused with mapping_incomplete. Optionally saved as the template preset.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mapping": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 500 } }, "saveAsPreset": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "mapping" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "postbatchId": { "type": "string" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "UPLOADED", "PARSING", "PARSED", "MAPPED", "PROCESSING", "DONE", "FAILED", "CANCELLED" ] }, "encoding": { "type": [ "string", "null" ] }, "delimiter": { "type": [ "string", "null" ] }, "headers": { "type": "array", "items": { "type": "string" } }, "sampleRows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "rowCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "malformedRows": { "type": "array", "items": { "type": "integer" } }, "targets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "recipient", "variable" ] } }, "required": [ "name", "required", "kind" ], "additionalProperties": false } }, "proposedMapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "mappingSource": { "type": [ "string", "null" ] }, "mapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unknown_target", "unknown_column", "unmapped_required", "unused_column", "empty_expression" ] }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "target": { "type": "string" }, "column": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "rowCounts": { "type": "object", "additionalProperties": { "type": "integer" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "line": { "type": "integer" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "parsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "postbatchId", "uploadId", "status", "encoding", "delimiter", "headers", "sampleRows", "rowCount", "malformedRows", "targets", "proposedMapping", "mappingSource", "mapping", "issues", "rowCounts", "errors", "parsedAt", "startedAt", "finishedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/import/process": { "post": { "operationId": "postbatches.processImport", "summary": "Process the import", "description": "Materialises the rows of a MAPPED import as items in chunks: validation like a Postflow item, in-file dedupe on the normalised address (duplicates kept as rows for the review), the suppression list, and the counts valid, needsAttention, suppressed, duplicates, processed and total. Poll GET .../import or stream .../import/progress; the Postbatch becomes VALIDATED with postbatch.validated.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "postbatchId": { "type": "string" }, "uploadId": { "type": "string" }, "status": { "type": "string", "enum": [ "UPLOADED", "PARSING", "PARSED", "MAPPED", "PROCESSING", "DONE", "FAILED", "CANCELLED" ] }, "encoding": { "type": [ "string", "null" ] }, "delimiter": { "type": [ "string", "null" ] }, "headers": { "type": "array", "items": { "type": "string" } }, "sampleRows": { "type": "array", "items": { "type": "object", "additionalProperties": { "type": "string" } } }, "rowCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "malformedRows": { "type": "array", "items": { "type": "integer" } }, "targets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "recipient", "variable" ] } }, "required": [ "name", "required", "kind" ], "additionalProperties": false } }, "proposedMapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "mappingSource": { "type": [ "string", "null" ] }, "mapping": { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string" } }, { "type": "null" } ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unknown_target", "unknown_column", "unmapped_required", "unused_column", "empty_expression" ] }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "target": { "type": "string" }, "column": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "rowCounts": { "type": "object", "additionalProperties": { "type": "integer" } }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "line": { "type": "integer" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "parsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "startedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "postbatchId", "uploadId", "status", "encoding", "delimiter", "headers", "sampleRows", "rowCount", "malformedRows", "targets", "proposedMapping", "mappingSource", "mapping", "issues", "rowCounts", "errors", "parsedAt", "startedAt", "finishedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/import/progress": { "get": { "operationId": "postbatches.importProgress", "summary": "Import progress stream", "description": "Server-sent events with the import view every second until the import ends.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Server-sent events", "content": { "text/event-stream": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/postbatches/{id}/import/rows": { "get": { "operationId": "postbatches.importRows", "summary": "Import rows that did not become items", "description": "The duplicate rows with their raw values and the item they duplicate (filter status=DUPLICATE or KEPT).", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rowNumber": { "type": "integer" }, "status": { "type": "string", "enum": [ "DUPLICATE", "KEPT" ] }, "raw": { "type": "object", "additionalProperties": { "type": "string" } }, "duplicateOfItemId": { "type": [ "string", "null" ] } }, "required": [ "id", "rowNumber", "status", "raw", "duplicateOfItemId" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/postbatches/{id}/import/rows/{rowId}/keep": { "post": { "operationId": "postbatches.keepDuplicate", "summary": "Keep a duplicate row", "description": "Materialises the duplicate row as an item after all.", "tags": [ "Postbatches" ], "parameters": [ { "name": "rowId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": [ "string", "null" ] }, "postbatch": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "required": [ "itemId", "postbatch" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/items": { "get": { "operationId": "postbatches.items", "summary": "List the items of a Postbatch", "description": "The item list conventions (status, needsAttention, externalId, createdAt, q and the other item filters) scoped to the Postbatch; cursor paged.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor of the previous page (same sort and filters).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma separated, prefix - for descending; fields: createdAt, sendDate. Default -createdAt.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "include=total adds totalCount.", "schema": { "type": "string", "enum": [ "total" ] } }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] } }, { "name": "filter[status][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[status][ne]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] } }, { "name": "filter[postflowId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[postflowId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[postbatchId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[postbatchId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[integrationInstallationId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[integrationInstallationId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[isTest]", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter[isSample]", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter[externalId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[externalId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[createdAt][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[sendDate][null]", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter[search][contains]", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "type": "integer" } }, "required": [ "data", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/postbatches/{id}/mapping-presets": { "get": { "operationId": "postbatches.mappingPresets", "summary": "Mapping targets and presets of the template", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "targets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "recipient", "variable" ] } }, "required": [ "name", "required", "kind" ], "additionalProperties": false } }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "name", "headers", "mapping" ], "additionalProperties": false } } }, "required": [ "targets", "presets" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/postbatches/{id}/proof": { "post": { "operationId": "postbatches.proof", "summary": "Proof PDF of a sample item", "description": "Renders the pinned template version with the recipient and variables of the chosen item; poll the render.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemId": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "itemId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "type": "object", "properties": { "variables": { "type": "object", "properties": {}, "additionalProperties": true }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false }, "urls": { "type": "object", "additionalProperties": { "type": "string" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "202": { "description": "The render is still running; poll it", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "type": "object", "properties": { "variables": { "type": "object", "properties": {}, "additionalProperties": true }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false }, "urls": { "type": "object", "additionalProperties": { "type": "string" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/postbatches/{id}/quote": { "get": { "operationId": "postbatches.quote", "summary": "Quote of a Postbatch", "description": "The number of items that will be sent, the unit price from your pricing on that quantity, totals excluding and including VAT, the next run with its cutoff and delivery window and the later planned runs you may pick at approval. Locked once approved.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postbatchId": { "type": "string" }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "quantity": { "type": "integer" }, "needsAttention": { "type": "integer" }, "suppressed": { "type": "integer" }, "duplicates": { "type": "integer" }, "currency": { "type": "string" }, "unitPriceCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "listUnitPriceCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "discountPercent": { "type": [ "number", "null" ] }, "tier": { "anyOf": [ { "type": "object", "properties": { "basis": { "type": "string", "const": "postbatch" }, "minQuantity": { "type": "integer" }, "basisQuantity": { "type": "integer" } }, "required": [ "basis", "minQuantity", "basisQuantity" ], "additionalProperties": false }, { "type": "null" } ] }, "totalExclVatCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "vatTreatment": { "type": [ "string", "null" ] }, "vatRate": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "vatCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "totalInclVatCents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "priced": { "type": "boolean" }, "nextRun": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "productGroup": { "type": "string" }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "cutoffAt": { "type": "string", "format": "date-time" }, "handoverWeek": { "type": "string" }, "handoverMonday": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "id", "cutoffAt", "handoverWeek", "handoverMonday" ], "additionalProperties": false }, "carrierLeadTimeDays": { "type": "integer" }, "processingDays": { "type": "integer" }, "leadTimeDays": { "type": "integer" }, "expectedDeliveryFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "productGroup", "run", "carrierLeadTimeDays", "processingDays", "leadTimeDays", "expectedDeliveryFrom" ], "additionalProperties": false }, { "type": "object", "properties": { "productGroup": { "type": "string" }, "run": { "type": "null" }, "carrierLeadTimeDays": { "type": "integer" } }, "required": [ "productGroup", "run", "carrierLeadTimeDays" ], "additionalProperties": false } ] }, { "type": "null" } ] }, "plannedRuns": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "cutoffAt": { "type": "string", "format": "date-time" }, "handoverWeek": { "type": "string" } }, "required": [ "id", "cutoffAt", "handoverWeek" ], "additionalProperties": false } }, "locked": { "type": "boolean" } }, "required": [ "postbatchId", "status", "quantity", "needsAttention", "suppressed", "duplicates", "currency", "unitPriceCents", "listUnitPriceCents", "discountPercent", "tier", "totalExclVatCents", "vatTreatment", "vatRate", "vatCents", "totalInclVatCents", "priced", "nextRun", "plannedRuns", "locked" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" } }, "/v1/postbatches/{id}/request-approval": { "post": { "operationId": "postbatches.requestApproval", "summary": "Request approval", "description": "VALIDATED to PENDING_APPROVAL; Owners, Admins and Approvers are notified.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postbatches/{id}/skip-attention": { "post": { "operationId": "postbatches.skipAttention", "summary": "Skip the items that need attention", "description": "Cancels every NEEDS_ATTENTION item of the Postbatch.", "tags": [ "Postbatches" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "campaignId": { "type": [ "string", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "DRAFT", "IMPORTING", "VALIDATED", "PENDING_APPROVAL", "APPROVED", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "CANCELLED" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "counts": { "type": "object", "additionalProperties": { "type": "integer" } }, "importId": { "type": [ "string", "null" ] }, "approvedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "targetRunId": { "type": [ "string", "null" ] }, "priceSnapshotId": { "type": [ "string", "null" ] }, "itemCountAtApproval": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "campaignId", "advertisingCategory", "status", "templateId", "templateVersionId", "product", "counts", "importId", "approvedAt", "targetRunId", "priceSnapshotId", "itemCountAtApproval", "cancelledAt", "completedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/postflows": { "get": { "operationId": "postflows.list", "summary": "List Postflows", "description": "Cursor paged (API-005) with held, ready, pending approval and needs attention counts; archived Postflows only with filter[status].", "tags": [ "Postflows" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor of the previous page (same sort and filters).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma separated, prefix - for descending; fields: createdAt, updatedAt, name. Default -updatedAt.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "include=total adds totalCount.", "schema": { "type": "string", "enum": [ "total" ] } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Without this filter ARCHIVED Postflows are hidden", "schema": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] } }, { "name": "filter[status][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[templateId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[templateId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[name]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[name][contains]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[dispatchStrategy]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] } }, { "name": "filter[dispatchStrategy][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "templateId": { "type": "string" }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ] }, "pinnedVersionId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] }, "minCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWaitDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "strictMinimum": { "type": "boolean" } }, "required": [ "strategy", "minCount", "maxWaitDays", "strictMinimum" ], "additionalProperties": false }, "requiresApproval": { "type": [ "boolean", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "counts": { "type": "object", "properties": { "held": { "type": "integer" }, "ready": { "type": "integer" }, "pendingApproval": { "type": "integer" }, "needsAttention": { "type": "integer" } }, "required": [ "held", "ready", "pendingApproval", "needsAttention" ], "additionalProperties": false } }, "required": [ "id", "name", "description", "status", "templateId", "versionPolicy", "pinnedVersionId", "productId", "productSpecificationId", "finish", "destination", "dispatch", "requiresApproval", "advertisingCategory", "createdAt", "updatedAt", "counts" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "type": "integer" } }, "required": [ "data", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.read" }, "post": { "operationId": "postflows.create", "summary": "Create a Postflow", "description": "The product follows from the template; the template needs a published version. Pause, resume, archive, stats and the list arrive with the next release.", "tags": [ "Postflows" ], "x-idempotent": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "maxLength": 2000 }, "templateId": { "type": "string", "minLength": 1 }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ], "default": "LATEST_PUBLISHED" }, "pinnedVersionId": { "type": "string", "minLength": 1 }, "finish": { "type": "string", "minLength": 1, "maxLength": 40 }, "destination": { "type": "string", "minLength": 2, "maxLength": 2, "default": "NL" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ], "default": "IMMEDIATE" }, "minCount": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "maxWaitDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "strictMinimum": { "type": "boolean", "default": false } }, "additionalProperties": false, "default": { "strategy": "IMMEDIATE", "strictMinimum": false } }, "requiresApproval": { "type": "boolean" }, "advertisingCategory": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "name", "templateId", "finish" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "templateId": { "type": "string" }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ] }, "pinnedVersionId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] }, "minCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWaitDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "strictMinimum": { "type": "boolean" } }, "required": [ "strategy", "minCount", "maxWaitDays", "strictMinimum" ], "additionalProperties": false }, "requiresApproval": { "type": [ "boolean", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "status", "templateId", "versionPolicy", "pinnedVersionId", "productId", "productSpecificationId", "finish", "destination", "dispatch", "requiresApproval", "advertisingCategory", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.write" } }, "/v1/postflows/{id}": { "get": { "operationId": "postflows.get", "summary": "Get a Postflow", "tags": [ "Postflows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "templateId": { "type": "string" }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ] }, "pinnedVersionId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] }, "minCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWaitDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "strictMinimum": { "type": "boolean" } }, "required": [ "strategy", "minCount", "maxWaitDays", "strictMinimum" ], "additionalProperties": false }, "requiresApproval": { "type": [ "boolean", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "status", "templateId", "versionPolicy", "pinnedVersionId", "productId", "productSpecificationId", "finish", "destination", "dispatch", "requiresApproval", "advertisingCategory", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.read" }, "patch": { "operationId": "postflows.patch", "summary": "Update a Postflow", "description": "Name, description, version policy, finish, destination, dispatch strategy and approval; the template cannot change.", "tags": [ "Postflows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "description": { "type": "string", "maxLength": 2000 }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ], "default": "LATEST_PUBLISHED" }, "pinnedVersionId": { "type": "string", "minLength": 1 }, "finish": { "type": "string", "minLength": 1, "maxLength": 40 }, "destination": { "type": "string", "minLength": 2, "maxLength": 2, "default": "NL" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ], "default": "IMMEDIATE" }, "minCount": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "maxWaitDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "strictMinimum": { "type": "boolean", "default": false } }, "additionalProperties": false, "default": { "strategy": "IMMEDIATE", "strictMinimum": false } }, "requiresApproval": { "type": "boolean" }, "advertisingCategory": { "anyOf": [ { "type": "string", "maxLength": 80 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "templateId": { "type": "string" }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ] }, "pinnedVersionId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] }, "minCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWaitDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "strictMinimum": { "type": "boolean" } }, "required": [ "strategy", "minCount", "maxWaitDays", "strictMinimum" ], "additionalProperties": false }, "requiresApproval": { "type": [ "boolean", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "status", "templateId", "versionPolicy", "pinnedVersionId", "productId", "productSpecificationId", "finish", "destination", "dispatch", "requiresApproval", "advertisingCategory", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Postflow archived (postflow_archived)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.write" } }, "/v1/postflows/{id}/approvals": { "post": { "operationId": "postflows.approve", "summary": "Approve pending items of a Postflow", "description": "Releases PENDING_APPROVAL items to READY for the next run: every pending item, or the given selection (POSTFLOW-005). Stops at the first funds refusal.", "tags": [ "Postflows" ], "x-idempotent": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "itemIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 1000 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "approved": { "type": "integer" }, "refused": { "type": [ "string", "null" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } }, "pending": { "type": "integer" } }, "required": [ "approved", "refused", "items", "pending" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.approve" } }, "/v1/postflows/{id}/archive": { "post": { "operationId": "postflows.archive", "summary": "Archive a Postflow", "description": "Refused while HELD, PENDING_APPROVAL or READY items exist unless cancelItems is true, which cancels them first.", "tags": [ "Postflows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "cancelItems": { "type": "boolean", "default": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "templateId": { "type": "string" }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ] }, "pinnedVersionId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] }, "minCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWaitDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "strictMinimum": { "type": "boolean" } }, "required": [ "strategy", "minCount", "maxWaitDays", "strictMinimum" ], "additionalProperties": false }, "requiresApproval": { "type": [ "boolean", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "status", "templateId", "versionPolicy", "pinnedVersionId", "productId", "productSpecificationId", "finish", "destination", "dispatch", "requiresApproval", "advertisingCategory", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.write" } }, "/v1/postflows/{id}/items": { "post": { "operationId": "postflows.createItem", "summary": "Create an item in a Postflow", "description": "Accepted with 202: the item starts HELD, or NEEDS_ATTENTION with warnings when the recipient or variables have content problems (repair in the portal or through PATCH), or SUPPRESSED when the address is on the suppression list. Test keys create test items.", "tags": [ "Items" ], "x-idempotent": true, "x-rate-limit-class": "itemCreate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "default": "" }, "addressLine1": { "type": "string", "maxLength": 200, "default": "" }, "addressLine2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20, "default": "" }, "city": { "type": "string", "maxLength": 120, "default": "" }, "country": { "type": "string", "maxLength": 40 } }, "additionalProperties": false }, "variables": { "type": "object", "additionalProperties": {}, "default": {} }, "sendDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "externalId": { "type": "string", "minLength": 1, "maxLength": 200 }, "metadata": { "type": "object", "additionalProperties": {} }, "advertisingCategory": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 80 }, { "type": "null" } ] } }, "required": [ "recipient" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.write" } }, "/v1/postflows/{id}/pause": { "post": { "operationId": "postflows.pause", "summary": "Pause a Postflow", "description": "HELD and READY items stay out of the cutoff; new items are still accepted (POSTFLOW-004).", "tags": [ "Postflows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "templateId": { "type": "string" }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ] }, "pinnedVersionId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] }, "minCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWaitDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "strictMinimum": { "type": "boolean" } }, "required": [ "strategy", "minCount", "maxWaitDays", "strictMinimum" ], "additionalProperties": false }, "requiresApproval": { "type": [ "boolean", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "status", "templateId", "versionPolicy", "pinnedVersionId", "productId", "productSpecificationId", "finish", "destination", "dispatch", "requiresApproval", "advertisingCategory", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.write" } }, "/v1/postflows/{id}/resume": { "post": { "operationId": "postflows.resume", "summary": "Resume a Postflow", "description": "Items are re-evaluated immediately.", "tags": [ "Postflows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "templateId": { "type": "string" }, "versionPolicy": { "type": "string", "enum": [ "LATEST_PUBLISHED", "PINNED" ] }, "pinnedVersionId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "dispatch": { "type": "object", "properties": { "strategy": { "type": "string", "enum": [ "IMMEDIATE", "SEND_DATE", "MIN_COUNT_MAX_WAIT" ] }, "minCount": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "maxWaitDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "strictMinimum": { "type": "boolean" } }, "required": [ "strategy", "minCount", "maxWaitDays", "strictMinimum" ], "additionalProperties": false }, "requiresApproval": { "type": [ "boolean", "null" ] }, "advertisingCategory": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "description", "status", "templateId", "versionPolicy", "pinnedVersionId", "productId", "productSpecificationId", "finish", "destination", "dispatch", "requiresApproval", "advertisingCategory", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.write" } }, "/v1/postflows/{id}/stats": { "get": { "operationId": "postflows.stats", "summary": "Postflow statistics", "description": "Counts by status, the next run, the oldest held item, the template version in use and recent items (POSTFLOW-006).", "tags": [ "Postflows" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "postflowId": { "type": "string" }, "status": { "type": "string", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "counts": { "type": "object", "properties": { "NEEDS_ATTENTION": { "type": "integer" }, "SUPPRESSED": { "type": "integer" }, "HELD": { "type": "integer" }, "PENDING_APPROVAL": { "type": "integer" }, "READY": { "type": "integer" }, "SCHEDULED_FOR_RUN": { "type": "integer" }, "IN_PRODUCTION": { "type": "integer" }, "COMPLETED": { "type": "integer" }, "FAILED": { "type": "integer" }, "CANCELLED": { "type": "integer" }, "RETURNED": { "type": "integer" }, "NOT_SENT": { "type": "integer" } }, "required": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ], "additionalProperties": false }, "scans": { "type": "object", "properties": { "itemsScanned": { "type": "integer" }, "scans": { "type": "integer" } }, "required": [ "itemsScanned", "scans" ], "additionalProperties": false }, "nextRun": { "anyOf": [ { "type": "object", "properties": { "runId": { "type": "string" }, "cutoffAt": { "type": "string", "format": "date-time" }, "handoverWeek": { "type": "string" }, "itemsReady": { "type": "integer" } }, "required": [ "runId", "cutoffAt", "handoverWeek", "itemsReady" ], "additionalProperties": false }, { "type": "null" } ] }, "oldestHeld": { "anyOf": [ { "type": "object", "properties": { "itemId": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "ageSeconds": { "type": "integer" } }, "required": [ "itemId", "createdAt", "ageSeconds" ], "additionalProperties": false }, { "type": "null" } ] }, "templateVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" } }, "required": [ "id", "number" ], "additionalProperties": false }, { "type": "null" } ] }, "recentItems": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } } }, "required": [ "postflowId", "status", "counts", "scans", "nextRun", "oldestHeld", "templateVersion", "recentItems" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postflows.read" } }, "/v1/previews/{id}": { "get": { "operationId": "renders.getPreview", "summary": "Get a preview request with its signed image URLs", "tags": [ "Renders" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "anyOf": [ { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "side": { "type": [ "string", "null" ] }, "dpi": { "type": "integer" }, "qrShortUrl": { "type": [ "string", "null" ] } }, "required": [ "variables", "recipient", "side", "dpi" ], "additionalProperties": false }, { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false } ] }, "urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/products": { "get": { "operationId": "products.list", "summary": "List active products with their current specification", "tags": [ "Products" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "POSTCARD", "GREETING_CARD", "LETTER", "SELF_MAILER" ] }, "productGroup": { "type": "string" }, "specification": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "RETIRED" ] }, "trimWidthMm": { "type": "number" }, "trimHeightMm": { "type": "number" }, "bleedMm": { "type": "number" }, "safeZoneMm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "PORTRAIT", "LANDSCAPE" ] }, "sides": { "type": "array", "items": { "type": "string" } }, "paper": { "type": "string" }, "allowedFinishes": { "type": "array", "items": { "type": "string" } }, "envelope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "windowSide": { "type": [ "string", "null" ] }, "window": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "type", "windowSide", "window" ], "additionalProperties": false }, { "type": "null" } ] }, "addressZone": { "type": "object", "properties": { "side": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "carrierRuleSet": { "type": "string" } }, "required": [ "side", "x", "y", "width", "height", "carrierRuleSet" ], "additionalProperties": false }, "postageZone": { "anyOf": [ { "type": "object", "properties": { "side": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "side", "x", "y", "width", "height" ], "additionalProperties": false }, { "type": "null" } ] }, "allowedDestinations": { "type": "array", "items": { "type": "string" } }, "weightClass": { "type": "string" }, "minImageDpi": { "type": "integer" }, "carrierLeadTimeDays": { "type": "integer" }, "hasBaseTemplate": { "type": "boolean" }, "baseVariables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "imageUrl", "url" ] }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "customer", "fixed" ] }, "value": { "type": "string" }, "fallback": { "type": "string" }, "maxLength": { "type": "integer" }, "format": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "type", "required" ], "additionalProperties": false } }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "retiredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "productId", "version", "status", "trimWidthMm", "trimHeightMm", "bleedMm", "safeZoneMm", "orientation", "sides", "paper", "allowedFinishes", "envelope", "addressZone", "postageZone", "allowedDestinations", "weightClass", "minImageDpi", "carrierLeadTimeDays", "hasBaseTemplate", "baseVariables", "publishedAt", "retiredAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "finishes": { "type": "array", "items": { "type": "string" } }, "destinations": { "type": "array", "items": { "type": "string" } }, "leadTimeDays": { "type": "integer" }, "carrierCodes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "symbology": { "type": "string", "enum": [ "text", "kix", "datamatrix", "gs1datamatrix", "code128" ] } }, "required": [ "key", "label", "symbology" ], "additionalProperties": false } } }, "required": [ "id", "key", "name", "description", "category", "productGroup", "specification", "finishes", "destinations", "leadTimeDays", "carrierCodes" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/products/{id}": { "get": { "operationId": "products.get", "summary": "Get a product", "tags": [ "Products" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "key": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "category": { "type": "string", "enum": [ "POSTCARD", "GREETING_CARD", "LETTER", "SELF_MAILER" ] }, "productGroup": { "type": "string" }, "specification": { "type": "object", "properties": { "id": { "type": "string" }, "productId": { "type": "string" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "DRAFT", "PUBLISHED", "RETIRED" ] }, "trimWidthMm": { "type": "number" }, "trimHeightMm": { "type": "number" }, "bleedMm": { "type": "number" }, "safeZoneMm": { "type": "number" }, "orientation": { "type": "string", "enum": [ "PORTRAIT", "LANDSCAPE" ] }, "sides": { "type": "array", "items": { "type": "string" } }, "paper": { "type": "string" }, "allowedFinishes": { "type": "array", "items": { "type": "string" } }, "envelope": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string" }, "windowSide": { "type": [ "string", "null" ] }, "window": { "anyOf": [ { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "type", "windowSide", "window" ], "additionalProperties": false }, { "type": "null" } ] }, "addressZone": { "type": "object", "properties": { "side": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "carrierRuleSet": { "type": "string" } }, "required": [ "side", "x", "y", "width", "height", "carrierRuleSet" ], "additionalProperties": false }, "postageZone": { "anyOf": [ { "type": "object", "properties": { "side": { "type": "string" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" } }, "required": [ "side", "x", "y", "width", "height" ], "additionalProperties": false }, { "type": "null" } ] }, "allowedDestinations": { "type": "array", "items": { "type": "string" } }, "weightClass": { "type": "string" }, "minImageDpi": { "type": "integer" }, "carrierLeadTimeDays": { "type": "integer" }, "hasBaseTemplate": { "type": "boolean" }, "baseVariables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "imageUrl", "url" ] }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "customer", "fixed" ] }, "value": { "type": "string" }, "fallback": { "type": "string" }, "maxLength": { "type": "integer" }, "format": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "type", "required" ], "additionalProperties": false } }, "publishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "retiredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "productId", "version", "status", "trimWidthMm", "trimHeightMm", "bleedMm", "safeZoneMm", "orientation", "sides", "paper", "allowedFinishes", "envelope", "addressZone", "postageZone", "allowedDestinations", "weightClass", "minImageDpi", "carrierLeadTimeDays", "hasBaseTemplate", "baseVariables", "publishedAt", "retiredAt", "createdAt", "updatedAt" ], "additionalProperties": false }, "finishes": { "type": "array", "items": { "type": "string" } }, "destinations": { "type": "array", "items": { "type": "string" } }, "leadTimeDays": { "type": "integer" }, "carrierCodes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "symbology": { "type": "string", "enum": [ "text", "kix", "datamatrix", "gs1datamatrix", "code128" ] } }, "required": [ "key", "label", "symbology" ], "additionalProperties": false } } }, "required": [ "id", "key", "name", "description", "category", "productGroup", "specification", "finishes", "destinations", "leadTimeDays", "carrierCodes" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/quotes": { "post": { "operationId": "pricing.quote", "summary": "Quote a price", "description": "The organisation's unit price for a product, finish and destination at a quantity, with the totals excluding and including VAT, the tier that applied and whether a pricing agreement was used. Postbatches quote at their own quantity; a Postflow item is priced at the organisation's rolling 30-day volume (basis rolling30d).", "tags": [ "Billing" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string", "minLength": 1 }, "finish": { "type": "string", "minLength": 1, "maxLength": 40 }, "destination": { "type": "string", "minLength": 2, "maxLength": 2, "default": "NL" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 10000000 }, "basis": { "type": "string", "enum": [ "postbatch", "rolling30d" ], "default": "postbatch" } }, "required": [ "productId", "finish", "quantity" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "productId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" }, "quantity": { "type": "integer" }, "currency": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "discountPercent": { "type": [ "number", "null" ] }, "agreementApplied": { "type": "boolean" }, "tier": { "type": "object", "properties": { "basis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "minQuantity": { "type": "integer" }, "basisQuantity": { "type": "integer" } }, "required": [ "basis", "minQuantity", "basisQuantity" ], "additionalProperties": false }, "totalExclVatCents": { "type": "integer" }, "vatCents": { "type": "integer" }, "totalInclVatCents": { "type": "integer" }, "vatTreatment": { "type": "string", "enum": [ "NL_STANDARD", "EU_REVERSE_CHARGE", "NON_EU" ] }, "vatRate": { "type": "integer" } }, "required": [ "productId", "finish", "destination", "quantity", "currency", "unitPriceCents", "listUnitPriceCents", "discountPercent", "agreementApplied", "tier", "totalExclVatCents", "vatCents", "totalInclVatCents", "vatTreatment", "vatRate" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "billing.read" } }, "/v1/runs/next": { "get": { "operationId": "runs.next", "summary": "Next planned production runs", "description": "Per product group: the next planned cutoff (Europe/Amsterdam), the expected handover week, the processing and carrier lead time and the earliest expected delivery date. Items released before the cutoff travel with that run.", "tags": [ "Runs" ], "parameters": [ { "name": "productGroup", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 60 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "productGroup": { "type": "string" }, "run": { "type": "object", "properties": { "id": { "type": "string" }, "cutoffAt": { "type": "string", "format": "date-time" }, "handoverWeek": { "type": "string" }, "handoverMonday": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "id", "cutoffAt", "handoverWeek", "handoverMonday" ], "additionalProperties": false }, "carrierLeadTimeDays": { "type": "integer" }, "processingDays": { "type": "integer" }, "leadTimeDays": { "type": "integer" }, "expectedDeliveryFrom": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, "required": [ "productGroup", "run", "carrierLeadTimeDays", "processingDays", "leadTimeDays", "expectedDeliveryFrom" ], "additionalProperties": false }, { "type": "object", "properties": { "productGroup": { "type": "string" }, "run": { "type": "null" }, "carrierLeadTimeDays": { "type": "integer" } }, "required": [ "productGroup", "run", "carrierLeadTimeDays" ], "additionalProperties": false } ] } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/status": { "get": { "operationId": "status.status", "summary": "Platform status: the components and their state from the last health check", "tags": [ "Status" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "down" ] }, "components": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "enum": [ "api", "processing", "events", "redirect", "backups" ] }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ] } }, "required": [ "name", "status" ], "additionalProperties": false } }, "checkedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "version": { "type": "string" }, "statusPageUrl": { "type": [ "string", "null" ] } }, "required": [ "status", "components", "checkedAt", "version", "statusPageUrl" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/v1/support/end": { "post": { "operationId": "support.endMine", "summary": "End the support session of the cookie early", "tags": [ "Support" ], "parameters": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "adminName": { "type": "string" }, "adminEmail": { "type": "string" }, "reason": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedBy": { "anyOf": [ { "type": "string", "enum": [ "ADMIN", "EXPIRY", "ORGANISATION" ] }, { "type": "null" } ] }, "exchangedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "blockedCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "ACTIVE", "ENDED" ] }, "remainingSeconds": { "type": "integer" } }, "required": [ "id", "organisationId", "adminName", "adminEmail", "reason", "startedAt", "expiresAt", "endedAt", "endedBy", "exchangedAt", "blockedCount", "status", "remainingSeconds" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/v1/support/exchange": { "post": { "operationId": "support.exchange", "summary": "Exchange a support handoff token for the support cookie", "tags": [ "Support" ], "x-rate-limit-class": "public", "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 10, "maxLength": 200 } }, "required": [ "token" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "adminName": { "type": "string" }, "adminEmail": { "type": "string" }, "reason": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedBy": { "anyOf": [ { "type": "string", "enum": [ "ADMIN", "EXPIRY", "ORGANISATION" ] }, { "type": "null" } ] }, "exchangedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "blockedCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "ACTIVE", "ENDED" ] }, "remainingSeconds": { "type": "integer" } }, "required": [ "id", "organisationId", "adminName", "adminEmail", "reason", "startedAt", "expiresAt", "endedAt", "endedBy", "exchangedAt", "blockedCount", "status", "remainingSeconds" ], "additionalProperties": false }, "organisation": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "locale": { "type": "string", "enum": [ "nl", "en" ] } }, "required": [ "id", "name", "slug", "locale" ], "additionalProperties": false } }, "required": [ "session", "organisation" ], "additionalProperties": false } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/v1/support/session": { "get": { "operationId": "support.current", "summary": "The support session of the cookie, if any", "tags": [ "Support" ], "parameters": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "session": { "type": "object", "properties": { "id": { "type": "string" }, "organisationId": { "type": "string" }, "adminName": { "type": "string" }, "adminEmail": { "type": "string" }, "reason": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "endedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "endedBy": { "anyOf": [ { "type": "string", "enum": [ "ADMIN", "EXPIRY", "ORGANISATION" ] }, { "type": "null" } ] }, "exchangedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "blockedCount": { "type": "integer" }, "status": { "type": "string", "enum": [ "ACTIVE", "ENDED" ] }, "remainingSeconds": { "type": "integer" } }, "required": [ "id", "organisationId", "adminName", "adminEmail", "reason", "startedAt", "expiresAt", "endedAt", "endedBy", "exchangedAt", "blockedCount", "status", "remainingSeconds" ], "additionalProperties": false } }, "required": [ "session" ], "additionalProperties": false } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [] } }, "/v1/suppression-reasons": { "get": { "operationId": "suppressionReasons.list", "summary": "List suppression reasons", "description": "Starts with opt_out, deceased, complaint and other; archived reasons are flagged and can no longer be chosen.", "tags": [ "SuppressionReasons" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "organisation" ] }, "sortOrder": { "type": "integer" }, "archived": { "type": "boolean" } }, "required": [ "key", "label", "source", "sortOrder", "archived" ], "additionalProperties": false } } }, "required": [ "data" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "post": { "operationId": "suppressionReasons.create", "summary": "Add a suppression reason", "description": "The key is derived from the label when absent.", "tags": [ "SuppressionReasons" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "key": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{1,40}$" }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "label" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "organisation" ] }, "sortOrder": { "type": "integer" }, "archived": { "type": "boolean" } }, "required": [ "key", "label", "source", "sortOrder", "archived" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" } }, "/v1/suppression-reasons/{key}": { "patch": { "operationId": "suppressionReasons.patch", "summary": "Rename, reorder or archive a suppression reason", "description": "At least one reason stays active.", "tags": [ "SuppressionReasons" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 80 }, "sortOrder": { "type": "integer", "minimum": 0, "maximum": 10000 }, "archived": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "source": { "type": "string", "enum": [ "platform", "organisation" ] }, "sortOrder": { "type": "integer" }, "archived": { "type": "boolean" } }, "required": [ "key", "label", "source", "sortOrder", "archived" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" }, "delete": { "operationId": "suppressionReasons.remove", "summary": "Delete a suppression reason", "description": "Refused while a suppression entry uses it.", "tags": [ "SuppressionReasons" ], "parameters": [ { "name": "key", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Still in use (still_referenced); archive it instead", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" } }, "/v1/suppressions": { "get": { "operationId": "suppressions.list", "summary": "List suppression entries", "description": "Cursor paged (API-005); search matches name, address line, postal code and city.", "tags": [ "Suppressions" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor of the previous page (same sort and filters).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma separated, prefix - for descending; fields: createdAt, postalCode, name. Default -createdAt.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "include=total adds totalCount.", "schema": { "type": "string", "enum": [ "total" ] } }, { "name": "filter[reason]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[source]", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "manual", "csv", "api" ] } }, { "name": "filter[source][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[country]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[createdAt][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[search][contains]", "in": "query", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "reason": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "manual", "csv", "api" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "addressLine1", "addressLine2", "postalCode", "city", "country", "reason", "categories", "source", "note", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "type": "integer" } }, "required": [ "data", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "post": { "operationId": "suppressions.add", "summary": "Add suppression entries", "description": "One address or an array of up to 1,000; addresses are normalised and matched on the delivery point. An entry without categories holds back all mail. Existing entries are reported and widened to the new categories; their reason and note stay.", "tags": [ "Suppressions" ], "x-idempotent": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "addressLine1": { "type": "string", "minLength": 1, "maxLength": 200 }, "addressLine2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20 }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country": { "type": "string", "maxLength": 40 }, "reason": { "type": "string", "minLength": 1, "maxLength": 60 }, "categories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 50 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "addressLine1", "postalCode", "city" ], "additionalProperties": false }, { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "addressLine1": { "type": "string", "minLength": 1, "maxLength": 200 }, "addressLine2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "minLength": 1, "maxLength": 20 }, "city": { "type": "string", "minLength": 1, "maxLength": 120 }, "country": { "type": "string", "maxLength": 40 }, "reason": { "type": "string", "minLength": 1, "maxLength": 60 }, "categories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 50 }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "addressLine1", "postalCode", "city" ], "additionalProperties": false }, "minItems": 1, "maxItems": 1000 } ] } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "reason": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "manual", "csv", "api" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "addressLine1", "addressLine2", "postalCode", "city", "country", "reason", "categories", "source", "note", "createdAt" ], "additionalProperties": false } }, "existing": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "reason": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "manual", "csv", "api" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "addressLine1", "addressLine2", "postalCode", "city", "country", "reason", "categories", "source", "note", "createdAt" ], "additionalProperties": false } } }, "required": [ "created", "existing" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" } }, "/v1/suppressions/{id}": { "get": { "operationId": "suppressions.get", "summary": "Get a suppression entry", "tags": [ "Suppressions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "reason": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "manual", "csv", "api" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "addressLine1", "addressLine2", "postalCode", "city", "country", "reason", "categories", "source", "note", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.read" }, "patch": { "operationId": "suppressions.patch", "summary": "Change a suppression entry", "description": "The reason, the advertising categories it holds back (empty for all mail) or the note; the address stays.", "tags": [ "Suppressions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "minLength": 1, "maxLength": 60 }, "categories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 50 }, "note": { "anyOf": [ { "type": "string", "maxLength": 500 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" }, "reason": { "type": "string" }, "categories": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string", "enum": [ "manual", "csv", "api" ] }, "note": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "addressLine1", "addressLine2", "postalCode", "city", "country", "reason", "categories", "source", "note", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" }, "delete": { "operationId": "suppressions.remove", "summary": "Remove a suppression entry", "tags": [ "Suppressions" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" } }, "/v1/suppressions/import": { "post": { "operationId": "suppressions.importCsv", "summary": "Import suppression entries from a CSV upload", "description": "A completed csv upload session; columns are mapped to the recipient fields by header name or through mapping. Rows that cannot be identified are reported by line.", "tags": [ "Suppressions" ], "x-idempotent": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "uploadId": { "type": "string", "minLength": 1 }, "reason": { "type": "string", "minLength": 1, "maxLength": 60 }, "categories": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 80 }, "maxItems": 50 }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "note": { "type": "string", "maxLength": 500 } }, "required": [ "uploadId" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "integer" }, "created": { "type": "integer" }, "existing": { "type": "integer" }, "invalid": { "type": "array", "items": { "type": "object", "properties": { "line": { "type": "integer" }, "problems": { "type": "array", "items": { "type": "string" } } }, "required": [ "line", "problems" ], "additionalProperties": false } }, "malformedLines": { "type": "array", "items": { "type": "integer" } }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "total": { "type": "integer" } }, "required": [ "rows", "created", "existing", "invalid", "malformedLines", "mapping", "total" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "More than 50,000 rows (import_too_large)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "suppressions.manage" } }, "/v1/template-folders": { "get": { "operationId": "templates.folders", "summary": "List template folders", "tags": [ "Templates" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "parentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" }, "post": { "operationId": "templates.createFolder", "summary": "Create a template folder", "tags": [ "Templates" ], "x-idempotent": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "default": null } }, "required": [ "name" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "parentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/template-folders/{id}": { "patch": { "operationId": "templates.patchFolder", "summary": "Rename or move a template folder", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "default": null } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "parentId": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "parentId", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" }, "delete": { "operationId": "templates.deleteFolder", "summary": "Delete a template folder", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "moveToParent", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Folder not empty (folder_not_empty)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/template-library": { "get": { "operationId": "templateLibrary.list", "summary": "List the template library of a product version", "description": "The ready-made designs PostBuddy publishes for the product specification version, with their categories and thumbnails (short-lived links). Create a template from one with `libraryDesignId`.", "tags": [ "TemplateLibrary" ], "parameters": [ { "name": "productSpecificationId", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameNl": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "nameNl" ], "additionalProperties": false } }, "designs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "nameNl": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "descriptionNl": { "type": [ "string", "null" ] }, "categoryIds": { "type": "array", "items": { "type": "string" } }, "thumbnails": { "type": "array", "items": { "type": "object", "properties": { "side": { "type": "string" }, "url": { "type": "string" } }, "required": [ "side", "url" ], "additionalProperties": false } } }, "required": [ "id", "name", "nameNl", "description", "descriptionNl", "categoryIds", "thumbnails" ], "additionalProperties": false } } }, "required": [ "categories", "designs" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/templates": { "get": { "operationId": "templates.list", "summary": "List templates", "description": "Cursor paged (API-005). Without filter[status] only ACTIVE templates are listed; use filter[folderId][null]=true for the root folder.", "tags": [ "Templates" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from nextCursor of the previous page (same sort and filters).", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "Comma separated, prefix - for descending; fields: createdAt, updatedAt, name. Default -updatedAt.", "schema": { "type": "string" } }, { "name": "include", "in": "query", "required": false, "description": "include=total adds totalCount.", "schema": { "type": "string", "enum": [ "total" ] } }, { "name": "filter[folderId]", "in": "query", "required": false, "description": "Folder id; filter[folderId][null]=true for the root", "schema": { "type": "string" } }, { "name": "filter[folderId][null]", "in": "query", "required": false, "schema": { "type": "boolean" } }, { "name": "filter[productId]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[productId][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[name]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[name][contains]", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "filter[status]", "in": "query", "required": false, "description": "Without this filter only ACTIVE templates are listed", "schema": { "type": "string", "enum": [ "ACTIVE", "ARCHIVED" ] } }, { "name": "filter[status][in]", "in": "query", "required": false, "schema": { "type": "string", "description": "Comma separated values" } }, { "name": "filter[createdAt][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[createdAt][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[updatedAt][gte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[updatedAt][gt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[updatedAt][lte]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "name": "filter[updatedAt][lt]", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "folderId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "draft": { "type": "object", "properties": { "revision": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedById": { "type": [ "string", "null" ] } }, "required": [ "revision", "updatedAt", "updatedById" ], "additionalProperties": false }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus" ], "additionalProperties": false }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "folderId", "productId", "productSpecificationId", "draft", "latestVersion", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" }, "totalCount": { "type": "integer" } }, "required": [ "data", "nextCursor", "hasMore" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" }, "post": { "operationId": "templates.create", "summary": "Create a template with an empty draft", "tags": [ "Templates" ], "x-idempotent": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "productSpecificationId": { "type": "string", "minLength": 1 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ], "default": null }, "libraryDesignId": { "type": "string", "minLength": 1 } }, "required": [ "name", "productSpecificationId" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "folderId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "draft": { "type": "object", "properties": { "revision": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedById": { "type": [ "string", "null" ] } }, "required": [ "revision", "updatedAt", "updatedById" ], "additionalProperties": false }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus" ], "additionalProperties": false }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "folderId", "productId", "productSpecificationId", "draft", "latestVersion", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/templates/{id}": { "get": { "operationId": "templates.get", "summary": "Get a template", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "folderId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "draft": { "type": "object", "properties": { "revision": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedById": { "type": [ "string", "null" ] } }, "required": [ "revision", "updatedAt", "updatedById" ], "additionalProperties": false }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus" ], "additionalProperties": false }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus" ], "additionalProperties": false } } }, "required": [ "id", "name", "folderId", "productId", "productSpecificationId", "draft", "latestVersion", "archivedAt", "createdAt", "updatedAt", "versions" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" }, "patch": { "operationId": "templates.patch", "summary": "Rename or move a template", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "folderId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "draft": { "type": "object", "properties": { "revision": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedById": { "type": [ "string", "null" ] } }, "required": [ "revision", "updatedAt", "updatedById" ], "additionalProperties": false }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus" ], "additionalProperties": false }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "folderId", "productId", "productSpecificationId", "draft", "latestVersion", "archivedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" }, "delete": { "operationId": "templates.archive", "summary": "Archive a template", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Template in use by a Postflow (template_in_use)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/templates/{id}/draft": { "get": { "operationId": "templates.draft", "summary": "Get the draft document and its revision", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "product": { "type": "object", "properties": { "specificationId": { "type": "string", "minLength": 1 }, "trimWidthMm": { "type": "number", "exclusiveMinimum": 0 }, "trimHeightMm": { "type": "number", "exclusiveMinimum": 0 }, "bleedMm": { "type": "number", "minimum": 0 }, "safeZoneMm": { "type": "number", "minimum": 0 } }, "required": [ "specificationId", "trimWidthMm", "trimHeightMm", "bleedMm", "safeZoneMm" ], "additionalProperties": false }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "side": { "type": "string", "minLength": 1, "maxLength": 32 }, "elements": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "fitMode": { "type": "string", "enum": [ "none", "shrink" ] }, "minFontSizePt": { "type": "number", "exclusiveMinimum": 0 }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "padding": { "type": "object", "properties": { "top": { "type": "number", "minimum": 0 }, "right": { "type": "number", "minimum": 0 }, "bottom": { "type": "number", "minimum": 0 }, "left": { "type": "number", "minimum": 0 } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, "defaultStyle": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "paragraphs": { "type": "array", "items": { "type": "object", "properties": { "align": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 }, "spaceBeforeMm": { "type": "number", "minimum": 0 }, "spaceAfterMm": { "type": "number", "minimum": 0 }, "list": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bullet", "number" ] }, "level": { "type": "integer", "minimum": 0, "maximum": 5 }, "marker": { "type": "string", "maxLength": 4 } }, "required": [ "kind", "level" ], "additionalProperties": false }, { "type": "null" } ] }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "runs": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "variable": { "type": "string", "pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|carrier\\.[a-z][A-Za-z0-9]{0,39}|recipient\\.(?:name|addressLine1|addressLine2|postalCode|city|country))$" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": [ "align", "lineHeight", "spaceBeforeMm", "spaceAfterMm", "list", "runs" ], "additionalProperties": false }, "maxItems": 50 }, "autoHeight": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "fitMode", "minFontSizePt", "verticalAlign", "padding", "defaultStyle", "paragraphs" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "asset" }, "assetId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "assetId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "variable" }, "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "fallbackAssetId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "kind", "variable", "fallbackAssetId" ], "additionalProperties": false } ] }, "fit": { "type": "string", "enum": [ "cover", "contain", "stretch" ] }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false }, "crop": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "flipH": { "type": "boolean" }, "flipV": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "source", "fit", "focalPoint", "crop", "cornerRadiusMm", "flipH", "flipV" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "shape": { "type": "string", "enum": [ "rect", "ellipse", "line", "polygon" ] }, "fill": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "stroke": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "widthMm": { "type": "number", "minimum": 0 }, "dash": { "type": "array", "items": { "type": "number", "minimum": 0 } } }, "required": [ "widthMm" ], "additionalProperties": false }, { "type": "null" } ] }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "points": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "shape", "fill", "stroke", "cornerRadiusMm", "points" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "qr" }, "urlExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "ecLevel": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "background": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ] }, "quietZoneModules": { "type": "integer", "minimum": 0, "maximum": 10 }, "trackable": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "urlExpression", "ecLevel", "color", "background", "quietZoneModules", "trackable" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "barcode" }, "symbology": { "type": "string", "enum": [ "code128", "ean13", "kix", "datamatrix", "gs1datamatrix" ] }, "valueExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "showText": { "type": "boolean" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "symbology", "valueExpression", "showText", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "group" }, "children": { "type": "array", "items": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "children" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "addressBlock" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "fontId", "sizePt", "color", "lineHeight" ], "additionalProperties": false }, "showSenderLine": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "style", "showSenderLine" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "postageIndicia" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "unknown" }, "raw": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "raw" ], "additionalProperties": false } ] }, "maxItems": 500 } }, "required": [ "id", "side", "elements" ], "additionalProperties": false }, "minItems": 1 }, "colors": { "type": "object", "additionalProperties": { "type": "object", "properties": { "rgb": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "cmyk": { "type": "array", "minItems": 4, "maxItems": 4, "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "rgb" ], "additionalProperties": false } }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "curated", "organisation", "google" ] } }, "required": [ "id", "family", "source" ], "additionalProperties": false } }, "meta": { "type": "object", "additionalProperties": {} } }, "required": [ "schemaVersion", "product", "pages", "colors", "fonts" ], "additionalProperties": false }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "imageUrl", "url" ] }, "required": { "type": "boolean" }, "fallback": { "type": "string" }, "maxLength": { "type": "integer" }, "format": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "type", "required" ], "additionalProperties": false } }, "revision": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedById": { "type": [ "string", "null" ] } }, "required": [ "templateId", "document", "variables", "revision", "updatedAt", "updatedById" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" }, "put": { "operationId": "templates.saveDraft", "summary": "Save the draft document", "description": "Send the revision from the last read in If-Match; a stale revision answers 412.", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "force", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "true", "false" ] } }, { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "document": {}, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "imageUrl", "url" ] }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "customer", "fixed" ] }, "value": { "type": "string", "maxLength": 2000 }, "fallback": { "type": "string", "maxLength": 2000 }, "maxLength": { "type": "integer", "exclusiveMinimum": 0, "maximum": 10000 }, "format": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 } }, "required": [ "name", "type", "required" ], "additionalProperties": false }, "maxItems": 200, "default": [] } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "product": { "type": "object", "properties": { "specificationId": { "type": "string", "minLength": 1 }, "trimWidthMm": { "type": "number", "exclusiveMinimum": 0 }, "trimHeightMm": { "type": "number", "exclusiveMinimum": 0 }, "bleedMm": { "type": "number", "minimum": 0 }, "safeZoneMm": { "type": "number", "minimum": 0 } }, "required": [ "specificationId", "trimWidthMm", "trimHeightMm", "bleedMm", "safeZoneMm" ], "additionalProperties": false }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "side": { "type": "string", "minLength": 1, "maxLength": 32 }, "elements": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "fitMode": { "type": "string", "enum": [ "none", "shrink" ] }, "minFontSizePt": { "type": "number", "exclusiveMinimum": 0 }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "padding": { "type": "object", "properties": { "top": { "type": "number", "minimum": 0 }, "right": { "type": "number", "minimum": 0 }, "bottom": { "type": "number", "minimum": 0 }, "left": { "type": "number", "minimum": 0 } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, "defaultStyle": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "paragraphs": { "type": "array", "items": { "type": "object", "properties": { "align": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 }, "spaceBeforeMm": { "type": "number", "minimum": 0 }, "spaceAfterMm": { "type": "number", "minimum": 0 }, "list": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bullet", "number" ] }, "level": { "type": "integer", "minimum": 0, "maximum": 5 }, "marker": { "type": "string", "maxLength": 4 } }, "required": [ "kind", "level" ], "additionalProperties": false }, { "type": "null" } ] }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "runs": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "variable": { "type": "string", "pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|carrier\\.[a-z][A-Za-z0-9]{0,39}|recipient\\.(?:name|addressLine1|addressLine2|postalCode|city|country))$" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": [ "align", "lineHeight", "spaceBeforeMm", "spaceAfterMm", "list", "runs" ], "additionalProperties": false }, "maxItems": 50 }, "autoHeight": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "fitMode", "minFontSizePt", "verticalAlign", "padding", "defaultStyle", "paragraphs" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "asset" }, "assetId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "assetId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "variable" }, "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "fallbackAssetId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "kind", "variable", "fallbackAssetId" ], "additionalProperties": false } ] }, "fit": { "type": "string", "enum": [ "cover", "contain", "stretch" ] }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false }, "crop": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "flipH": { "type": "boolean" }, "flipV": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "source", "fit", "focalPoint", "crop", "cornerRadiusMm", "flipH", "flipV" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "shape": { "type": "string", "enum": [ "rect", "ellipse", "line", "polygon" ] }, "fill": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "stroke": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "widthMm": { "type": "number", "minimum": 0 }, "dash": { "type": "array", "items": { "type": "number", "minimum": 0 } } }, "required": [ "widthMm" ], "additionalProperties": false }, { "type": "null" } ] }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "points": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "shape", "fill", "stroke", "cornerRadiusMm", "points" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "qr" }, "urlExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "ecLevel": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "background": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ] }, "quietZoneModules": { "type": "integer", "minimum": 0, "maximum": 10 }, "trackable": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "urlExpression", "ecLevel", "color", "background", "quietZoneModules", "trackable" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "barcode" }, "symbology": { "type": "string", "enum": [ "code128", "ean13", "kix", "datamatrix", "gs1datamatrix" ] }, "valueExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "showText": { "type": "boolean" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "symbology", "valueExpression", "showText", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "group" }, "children": { "type": "array", "items": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "children" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "addressBlock" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "fontId", "sizePt", "color", "lineHeight" ], "additionalProperties": false }, "showSenderLine": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "style", "showSenderLine" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "postageIndicia" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "unknown" }, "raw": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "raw" ], "additionalProperties": false } ] }, "maxItems": 500 } }, "required": [ "id", "side", "elements" ], "additionalProperties": false }, "minItems": 1 }, "colors": { "type": "object", "additionalProperties": { "type": "object", "properties": { "rgb": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "cmyk": { "type": "array", "minItems": 4, "maxItems": 4, "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "rgb" ], "additionalProperties": false } }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "curated", "organisation", "google" ] } }, "required": [ "id", "family", "source" ], "additionalProperties": false } }, "meta": { "type": "object", "additionalProperties": {} } }, "required": [ "schemaVersion", "product", "pages", "colors", "fonts" ], "additionalProperties": false }, "variables": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "imageUrl", "url" ] }, "required": { "type": "boolean" }, "fallback": { "type": "string" }, "maxLength": { "type": "integer" }, "format": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "type", "required" ], "additionalProperties": false } }, "revision": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedById": { "type": [ "string", "null" ] } }, "required": [ "templateId", "document", "variables", "revision", "updatedAt", "updatedById" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "Draft was modified elsewhere (draft_conflict)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/templates/{id}/duplicate": { "post": { "operationId": "templates.duplicate", "summary": "Duplicate a template", "tags": [ "Templates" ], "x-idempotent": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "productSpecificationId": { "type": "string", "minLength": 1 }, "folderId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "folderId": { "type": [ "string", "null" ] }, "productId": { "type": "string" }, "productSpecificationId": { "type": "string" }, "draft": { "type": "object", "properties": { "revision": { "type": "integer" }, "updatedAt": { "type": "string", "format": "date-time" }, "updatedById": { "type": [ "string", "null" ] } }, "required": [ "revision", "updatedAt", "updatedById" ], "additionalProperties": false }, "latestVersion": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus" ], "additionalProperties": false }, { "type": "null" } ] }, "archivedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "warnings": { "type": "array", "items": { "type": "string" } } }, "required": [ "id", "name", "folderId", "productId", "productSpecificationId", "draft", "latestVersion", "archivedAt", "createdAt", "updatedAt", "warnings" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/templates/{id}/mapping-presets": { "get": { "operationId": "mappingPresets.list", "summary": "List mapping presets of a template", "tags": [ "MappingPresets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "templateId": { "type": "string" }, "name": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "createdByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "createdById": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "templateId", "name", "headers", "mapping", "createdByType", "createdById", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" }, "post": { "operationId": "mappingPresets.create", "summary": "Create a mapping preset", "tags": [ "MappingPresets" ], "x-idempotent": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "headers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 500 }, "mapping": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } } }, "required": [ "name", "headers", "mapping" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "templateId": { "type": "string" }, "name": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "createdByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "createdById": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "templateId", "name", "headers", "mapping", "createdByType", "createdById", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/templates/{id}/mapping-presets/{pid}": { "patch": { "operationId": "mappingPresets.patch", "summary": "Update a mapping preset", "tags": [ "MappingPresets" ], "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "headers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 500 }, "mapping": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "templateId": { "type": "string" }, "name": { "type": "string" }, "headers": { "type": "array", "items": { "type": "string" } }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "createdByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "createdById": { "type": "string" }, "lastUsedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "templateId", "name", "headers", "mapping", "createdByType", "createdById", "lastUsedAt", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" }, "delete": { "operationId": "mappingPresets.delete", "summary": "Delete a mapping preset", "tags": [ "MappingPresets" ], "parameters": [ { "name": "pid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "postbatches.write" } }, "/v1/templates/{id}/mapping-presets/suggest": { "post": { "operationId": "mappingPresets.suggest", "summary": "Suggest a mapping for CSV headers", "tags": [ "MappingPresets" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "headers": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 500 }, "mapping": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } } }, "required": [ "headers" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "preset": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "similarity": { "type": "number" } }, "required": [ "id", "name", "similarity" ], "additionalProperties": false }, { "type": "null" } ] }, "targets": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "required": { "type": "boolean" }, "kind": { "type": "string", "enum": [ "recipient", "variable" ] } }, "required": [ "name", "required", "kind" ], "additionalProperties": false } }, "mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unknown_target", "unknown_column", "unmapped_required", "unused_column", "empty_expression" ] }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "target": { "type": "string" }, "column": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } } }, "required": [ "preset", "targets", "mapping", "issues" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/templates/{id}/publish": { "post": { "operationId": "templates.publish", "summary": "Publish the draft as a new version", "tags": [ "Templates" ], "x-idempotent": true, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "sampleVariables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 } }, "sampleRecipient": { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] }, "templateId": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "product": { "type": "object", "properties": { "specificationId": { "type": "string", "minLength": 1 }, "trimWidthMm": { "type": "number", "exclusiveMinimum": 0 }, "trimHeightMm": { "type": "number", "exclusiveMinimum": 0 }, "bleedMm": { "type": "number", "minimum": 0 }, "safeZoneMm": { "type": "number", "minimum": 0 } }, "required": [ "specificationId", "trimWidthMm", "trimHeightMm", "bleedMm", "safeZoneMm" ], "additionalProperties": false }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "side": { "type": "string", "minLength": 1, "maxLength": 32 }, "elements": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "fitMode": { "type": "string", "enum": [ "none", "shrink" ] }, "minFontSizePt": { "type": "number", "exclusiveMinimum": 0 }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "padding": { "type": "object", "properties": { "top": { "type": "number", "minimum": 0 }, "right": { "type": "number", "minimum": 0 }, "bottom": { "type": "number", "minimum": 0 }, "left": { "type": "number", "minimum": 0 } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, "defaultStyle": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "paragraphs": { "type": "array", "items": { "type": "object", "properties": { "align": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 }, "spaceBeforeMm": { "type": "number", "minimum": 0 }, "spaceAfterMm": { "type": "number", "minimum": 0 }, "list": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bullet", "number" ] }, "level": { "type": "integer", "minimum": 0, "maximum": 5 }, "marker": { "type": "string", "maxLength": 4 } }, "required": [ "kind", "level" ], "additionalProperties": false }, { "type": "null" } ] }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "runs": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "variable": { "type": "string", "pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|carrier\\.[a-z][A-Za-z0-9]{0,39}|recipient\\.(?:name|addressLine1|addressLine2|postalCode|city|country))$" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": [ "align", "lineHeight", "spaceBeforeMm", "spaceAfterMm", "list", "runs" ], "additionalProperties": false }, "maxItems": 50 }, "autoHeight": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "fitMode", "minFontSizePt", "verticalAlign", "padding", "defaultStyle", "paragraphs" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "asset" }, "assetId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "assetId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "variable" }, "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "fallbackAssetId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "kind", "variable", "fallbackAssetId" ], "additionalProperties": false } ] }, "fit": { "type": "string", "enum": [ "cover", "contain", "stretch" ] }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false }, "crop": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "flipH": { "type": "boolean" }, "flipV": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "source", "fit", "focalPoint", "crop", "cornerRadiusMm", "flipH", "flipV" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "shape": { "type": "string", "enum": [ "rect", "ellipse", "line", "polygon" ] }, "fill": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "stroke": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "widthMm": { "type": "number", "minimum": 0 }, "dash": { "type": "array", "items": { "type": "number", "minimum": 0 } } }, "required": [ "widthMm" ], "additionalProperties": false }, { "type": "null" } ] }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "points": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "shape", "fill", "stroke", "cornerRadiusMm", "points" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "qr" }, "urlExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "ecLevel": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "background": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ] }, "quietZoneModules": { "type": "integer", "minimum": 0, "maximum": 10 }, "trackable": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "urlExpression", "ecLevel", "color", "background", "quietZoneModules", "trackable" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "barcode" }, "symbology": { "type": "string", "enum": [ "code128", "ean13", "kix", "datamatrix", "gs1datamatrix" ] }, "valueExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "showText": { "type": "boolean" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "symbology", "valueExpression", "showText", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "group" }, "children": { "type": "array", "items": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "children" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "addressBlock" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "fontId", "sizePt", "color", "lineHeight" ], "additionalProperties": false }, "showSenderLine": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "style", "showSenderLine" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "postageIndicia" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "unknown" }, "raw": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "raw" ], "additionalProperties": false } ] }, "maxItems": 500 } }, "required": [ "id", "side", "elements" ], "additionalProperties": false }, "minItems": 1 }, "colors": { "type": "object", "additionalProperties": { "type": "object", "properties": { "rgb": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "cmyk": { "type": "array", "minItems": 4, "maxItems": 4, "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "rgb" ], "additionalProperties": false } }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "curated", "organisation", "google" ] } }, "required": [ "id", "family", "source" ], "additionalProperties": false } }, "meta": { "type": "object", "additionalProperties": {} } }, "required": [ "schemaVersion", "product", "pages", "colors", "fonts" ], "additionalProperties": false }, "schemaVersion": { "type": "integer" }, "variableSchema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "imageUrl", "url" ] }, "required": { "type": "boolean" }, "fallback": { "type": "string" }, "maxLength": { "type": "integer" }, "format": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "type", "required" ], "additionalProperties": false } }, "staticElementIds": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "pageId": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus", "templateId", "document", "schemaVersion", "variableSchema", "staticElementIds", "warnings" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/templates/{id}/versions": { "get": { "operationId": "templates.versions", "summary": "List template versions", "tags": [ "Templates" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/templates/{id}/versions/{number}": { "get": { "operationId": "templates.version", "summary": "Get a template version with its document and variable schema", "tags": [ "Templates" ], "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "number": { "type": "integer" }, "publishedAt": { "type": "string", "format": "date-time" }, "publishedByType": { "type": "string", "enum": [ "USER", "API_KEY" ] }, "publishedById": { "type": "string" }, "staticLayerStatus": { "type": "string", "enum": [ "PENDING", "READY", "FAILED" ] }, "templateId": { "type": "string" }, "document": { "type": "object", "properties": { "schemaVersion": { "type": "number", "const": 1 }, "product": { "type": "object", "properties": { "specificationId": { "type": "string", "minLength": 1 }, "trimWidthMm": { "type": "number", "exclusiveMinimum": 0 }, "trimHeightMm": { "type": "number", "exclusiveMinimum": 0 }, "bleedMm": { "type": "number", "minimum": 0 }, "safeZoneMm": { "type": "number", "minimum": 0 } }, "required": [ "specificationId", "trimWidthMm", "trimHeightMm", "bleedMm", "safeZoneMm" ], "additionalProperties": false }, "pages": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "side": { "type": "string", "minLength": 1, "maxLength": 32 }, "elements": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "text" }, "fitMode": { "type": "string", "enum": [ "none", "shrink" ] }, "minFontSizePt": { "type": "number", "exclusiveMinimum": 0 }, "verticalAlign": { "type": "string", "enum": [ "top", "middle", "bottom" ] }, "padding": { "type": "object", "properties": { "top": { "type": "number", "minimum": 0 }, "right": { "type": "number", "minimum": 0 }, "bottom": { "type": "number", "minimum": 0 }, "left": { "type": "number", "minimum": 0 } }, "required": [ "top", "right", "bottom", "left" ], "additionalProperties": false }, "defaultStyle": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "paragraphs": { "type": "array", "items": { "type": "object", "properties": { "align": { "type": "string", "enum": [ "left", "center", "right", "justify" ] }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 }, "spaceBeforeMm": { "type": "number", "minimum": 0 }, "spaceAfterMm": { "type": "number", "minimum": 0 }, "list": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "bullet", "number" ] }, "level": { "type": "integer", "minimum": 0, "maximum": 5 }, "marker": { "type": "string", "maxLength": 4 } }, "required": [ "kind", "level" ], "additionalProperties": false }, { "type": "null" } ] }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false }, "runs": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "variable": { "type": "string", "pattern": "^(?:[A-Za-z_][A-Za-z0-9_]*|carrier\\.[a-z][A-Za-z0-9]{0,39}|recipient\\.(?:name|addressLine1|addressLine2|postalCode|city|country))$" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "weight": { "type": "integer", "minimum": 100, "maximum": 900 }, "italic": { "type": "boolean" }, "underline": { "type": "boolean" }, "strike": { "type": "boolean" }, "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "letterSpacingPt": { "type": "number" } }, "additionalProperties": false } }, "additionalProperties": false } } }, "required": [ "align", "lineHeight", "spaceBeforeMm", "spaceAfterMm", "list", "runs" ], "additionalProperties": false }, "maxItems": 50 }, "autoHeight": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "fitMode", "minFontSizePt", "verticalAlign", "padding", "defaultStyle", "paragraphs" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "image" }, "source": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "asset" }, "assetId": { "type": "string", "minLength": 1 } }, "required": [ "kind", "assetId" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "type": "string", "const": "variable" }, "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "fallbackAssetId": { "anyOf": [ { "type": "string", "minLength": 1 }, { "type": "null" } ] } }, "required": [ "kind", "variable", "fallbackAssetId" ], "additionalProperties": false } ] }, "fit": { "type": "string", "enum": [ "cover", "contain", "stretch" ] }, "focalPoint": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y" ], "additionalProperties": false }, "crop": { "type": "object", "properties": { "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "minimum": 0, "maximum": 1 } }, "required": [ "x", "y", "width", "height" ], "additionalProperties": false }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "flipH": { "type": "boolean" }, "flipV": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "source", "fit", "focalPoint", "crop", "cornerRadiusMm", "flipH", "flipV" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "shape" }, "shape": { "type": "string", "enum": [ "rect", "ellipse", "line", "polygon" ] }, "fill": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "additionalProperties": false }, { "type": "null" } ] }, "stroke": { "anyOf": [ { "type": "object", "properties": { "colorRef": { "type": "string", "minLength": 1 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "widthMm": { "type": "number", "minimum": 0 }, "dash": { "type": "array", "items": { "type": "number", "minimum": 0 } } }, "required": [ "widthMm" ], "additionalProperties": false }, { "type": "null" } ] }, "cornerRadiusMm": { "type": "number", "minimum": 0 }, "points": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ], "additionalProperties": false } }, { "type": "null" } ] } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "shape", "fill", "stroke", "cornerRadiusMm", "points" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "qr" }, "urlExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "ecLevel": { "type": "string", "enum": [ "L", "M", "Q", "H" ] }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "background": { "anyOf": [ { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, { "type": "null" } ] }, "quietZoneModules": { "type": "integer", "minimum": 0, "maximum": 10 }, "trackable": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "urlExpression", "ecLevel", "color", "background", "quietZoneModules", "trackable" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "barcode" }, "symbology": { "type": "string", "enum": [ "code128", "ean13", "kix", "datamatrix", "gs1datamatrix" ] }, "valueExpression": { "type": "string", "minLength": 1, "maxLength": 2048 }, "showText": { "type": "boolean" }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "symbology", "valueExpression", "showText", "color" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "group" }, "children": { "type": "array", "items": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "children" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "addressBlock" }, "style": { "type": "object", "properties": { "fontId": { "type": "string", "minLength": 1 }, "sizePt": { "type": "number", "exclusiveMinimum": 0 }, "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "lineHeight": { "type": "number", "exclusiveMinimum": 0 } }, "required": [ "fontId", "sizePt", "color", "lineHeight" ], "additionalProperties": false }, "showSenderLine": { "type": "boolean" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "style", "showSenderLine" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean", "const": true }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "postageIndicia" } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[a-z]{2,8}_[0-9A-HJKMNP-TV-Z]{26}$" }, "name": { "type": "string", "maxLength": 200 }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number", "minimum": 0 }, "height": { "type": "number", "minimum": 0 }, "rotation": { "type": "number" }, "opacity": { "type": "number", "minimum": 0, "maximum": 1 }, "locked": { "type": "boolean" }, "hidden": { "type": "boolean" }, "visibleIf": { "anyOf": [ { "type": "object", "properties": { "variable": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "op": { "type": "string", "enum": [ "isSet", "isNotSet", "equals", "notEquals" ] }, "value": { "type": "string" } }, "required": [ "variable", "op" ], "additionalProperties": false }, { "type": "null" } ] }, "system": { "type": "boolean" }, "scopes": { "anyOf": [ { "type": "object", "properties": { "move": { "type": "boolean" }, "resize": { "type": "boolean" }, "rotate": { "type": "boolean" }, "content": { "type": "boolean" }, "style": { "type": "boolean" }, "arrange": { "type": "boolean" }, "hide": { "type": "boolean" }, "delete": { "type": "boolean" } }, "required": [ "move", "resize", "rotate", "content", "style", "arrange", "hide", "delete" ], "additionalProperties": false }, { "type": "null" } ] }, "onTop": { "type": "boolean" }, "keepClear": { "type": "boolean" }, "type": { "type": "string", "const": "unknown" }, "raw": { "type": "object", "additionalProperties": {} } }, "required": [ "id", "x", "y", "width", "height", "rotation", "opacity", "locked", "hidden", "visibleIf", "system", "type", "raw" ], "additionalProperties": false } ] }, "maxItems": 500 } }, "required": [ "id", "side", "elements" ], "additionalProperties": false }, "minItems": 1 }, "colors": { "type": "object", "additionalProperties": { "type": "object", "properties": { "rgb": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "cmyk": { "type": "array", "minItems": 4, "maxItems": 4, "items": [ { "type": "number" }, { "type": "number" }, { "type": "number" }, { "type": "number" } ] } }, "required": [ "rgb" ], "additionalProperties": false } }, "fonts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1 }, "family": { "type": "string", "minLength": 1 }, "source": { "type": "string", "enum": [ "curated", "organisation", "google" ] } }, "required": [ "id", "family", "source" ], "additionalProperties": false } }, "meta": { "type": "object", "additionalProperties": {} } }, "required": [ "schemaVersion", "product", "pages", "colors", "fonts" ], "additionalProperties": false }, "schemaVersion": { "type": "integer" }, "variableSchema": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date", "boolean", "imageUrl", "url" ] }, "required": { "type": "boolean" }, "fallback": { "type": "string" }, "maxLength": { "type": "integer" }, "format": { "type": "string" }, "description": { "type": "string" } }, "required": [ "name", "type", "required" ], "additionalProperties": false } }, "staticElementIds": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "id", "number", "publishedAt", "publishedByType", "publishedById", "staticLayerStatus", "templateId", "document", "schemaVersion", "variableSchema", "staticElementIds" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/templates/{id}/versions/{number}/previews": { "post": { "operationId": "renders.preview", "summary": "Request preview images of a version", "description": "Answers 202 while rendering and 200 when an identical request was rendered before; poll GET /v1/previews/{id}.", "tags": [ "Renders" ], "x-rate-limit-class": "preview", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 }, "default": {} }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "addressLine1": { "type": "string", "maxLength": 200 }, "addressLine2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, "side": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,30}$" }, "dpi": { "type": "integer", "minimum": 36, "maximum": 300, "default": 150 }, "qrShortUrl": { "type": "string", "format": "uri" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "anyOf": [ { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "side": { "type": [ "string", "null" ] }, "dpi": { "type": "integer" }, "qrShortUrl": { "type": [ "string", "null" ] } }, "required": [ "variables", "recipient", "side", "dpi" ], "additionalProperties": false }, { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false } ] }, "urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "202": { "description": "Rendering; poll the preview request", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "anyOf": [ { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "side": { "type": [ "string", "null" ] }, "dpi": { "type": "integer" }, "qrShortUrl": { "type": [ "string", "null" ] } }, "required": [ "variables", "recipient", "side", "dpi" ], "additionalProperties": false }, { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false } ] }, "urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/templates/{id}/versions/{number}/proof-pdf": { "post": { "operationId": "renders.proof", "summary": "Request a proof PDF of a version", "description": "Answers 202 while rendering and 200 when an identical request was rendered before; poll GET /v1/jobs/{id}.", "tags": [ "Renders" ], "x-rate-limit-class": "preview", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string", "maxLength": 2000 }, "default": {} }, "recipient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200 }, "addressLine1": { "type": "string", "maxLength": 200 }, "addressLine2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20 }, "city": { "type": "string", "maxLength": 100 }, "country": { "type": "string", "minLength": 2, "maxLength": 2 } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "anyOf": [ { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "side": { "type": [ "string", "null" ] }, "dpi": { "type": "integer" }, "qrShortUrl": { "type": [ "string", "null" ] } }, "required": [ "variables", "recipient", "side", "dpi" ], "additionalProperties": false }, { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false } ] }, "urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "202": { "description": "Rendering; poll the job", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "preview", "proof" ] }, "templateId": { "type": "string" }, "templateVersionId": { "type": "string" }, "status": { "type": "string", "enum": [ "PENDING", "RUNNING", "READY", "FAILED" ] }, "params": { "anyOf": [ { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "side": { "type": [ "string", "null" ] }, "dpi": { "type": "integer" }, "qrShortUrl": { "type": [ "string", "null" ] } }, "required": [ "variables", "recipient", "side", "dpi" ], "additionalProperties": false }, { "type": "object", "properties": { "variables": { "type": "object", "additionalProperties": { "type": "string" } }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": "string" }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "variables", "recipient" ], "additionalProperties": false } ] }, "urls": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string" }, "severity": { "type": "string", "enum": [ "error", "warning" ] }, "message": { "type": "string" }, "elementId": { "type": "string" } }, "required": [ "code", "severity", "message" ], "additionalProperties": false } }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "finishedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "id", "kind", "templateId", "templateVersionId", "status", "params", "urls", "issues", "error", "createdAt", "finishedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/templates/{id}/versions/{number}/samples": { "post": { "operationId": "samples.order", "summary": "Order a physical sample of a version", "description": "A paid single item (isSample) with the given recipient and sample data, priced as one piece and released to the next production run at once. Needs postbatches.write or postflows.write and the samples feature of the plan.", "tags": [ "Templates" ], "x-rate-limit-class": "itemCreate", "parameters": [ { "name": "number", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 200, "default": "" }, "addressLine1": { "type": "string", "maxLength": 200, "default": "" }, "addressLine2": { "type": "string", "maxLength": 200 }, "postalCode": { "type": "string", "maxLength": 20, "default": "" }, "city": { "type": "string", "maxLength": 120, "default": "" }, "country": { "type": "string", "maxLength": 40 } }, "additionalProperties": false }, "variables": { "type": "object", "additionalProperties": {}, "default": {} }, "finish": { "type": "string", "minLength": 1, "maxLength": 40 } }, "required": [ "recipient" ], "additionalProperties": false } } } }, "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "customerStatus": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "SCHEDULED", "IN_PRODUCTION", "HANDED_TO_CARRIER", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, "needsAttention": { "type": "boolean" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }, "field": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "field", "message" ], "additionalProperties": false } }, "source": { "type": "string", "enum": [ "POSTFLOW", "POSTBATCH", "SAMPLE" ] }, "postflowId": { "type": [ "string", "null" ] }, "postbatchId": { "type": [ "string", "null" ] }, "templateVersionId": { "type": [ "string", "null" ] }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "specificationId": { "type": "string" }, "finish": { "type": "string" }, "destination": { "type": "string" } }, "required": [ "id", "specificationId", "finish", "destination" ], "additionalProperties": false }, "advertisingCategory": { "type": [ "string", "null" ] }, "isTest": { "type": "boolean" }, "isSample": { "type": "boolean" }, "recipient": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string" }, "addressLine1": { "type": "string" }, "addressLine2": { "type": [ "string", "null" ] }, "postalCode": { "type": "string" }, "city": { "type": "string" }, "country": { "type": "string" } }, "required": [ "name", "addressLine1", "addressLine2", "postalCode", "city", "country" ], "additionalProperties": false }, { "type": "null" } ] }, "variables": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "sendDate": { "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, { "type": "null" } ] }, "externalId": { "type": [ "string", "null" ] }, "metadata": { "anyOf": [ { "type": "object", "properties": {}, "additionalProperties": true }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "scheduledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "handedToCarrierAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "failedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "cancelledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "anonymisedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "qr": { "anyOf": [ { "type": "object", "properties": { "shortUrl": { "type": "string" }, "scanCount": { "type": "integer" }, "firstScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastScannedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "required": [ "shortUrl", "scanCount", "firstScannedAt", "lastScannedAt" ], "additionalProperties": false }, { "type": "null" } ] }, "price": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "unitPriceCents": { "type": "integer" }, "listUnitPriceCents": { "type": "integer" }, "currency": { "type": "string" }, "discountPercent": { "type": [ "number", "null" ] }, "tierQuantity": { "type": "integer" }, "tierBasis": { "type": "string", "enum": [ "postbatch", "rolling30d" ] }, "basisQuantity": { "type": "integer" }, "vatTreatment": { "type": "string" }, "vatRate": { "type": "integer" }, "computedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "unitPriceCents", "listUnitPriceCents", "currency", "discountPercent", "tierQuantity", "tierBasis", "basisQuantity", "vatTreatment", "vatRate", "computedAt" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "status", "customerStatus", "needsAttention", "warnings", "source", "postflowId", "postbatchId", "templateVersionId", "product", "advertisingCategory", "isTest", "isSample", "recipient", "variables", "sendDate", "externalId", "metadata", "createdAt", "updatedAt", "readyAt", "scheduledAt", "handedToCarrierAt", "completedAt", "failedAt", "cancelledAt", "anonymisedAt", "qr", "price" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/test-runs": { "post": { "operationId": "testRuns.simulate", "summary": "Simulate a production run for test items", "description": "Moves READY test items (of the organisation, of one Postflow, or the listed ids) through SCHEDULED_FOR_RUN, IN_PRODUCTION, the carrier handoff and COMPLETED (or FAILED with outcome FAILED) in one call, so webhook handlers receive the full sequence. Nothing is printed, charged or handed to a carrier. Test keys and portal members only; live keys are refused.", "tags": [ "Developers" ], "x-idempotent": true, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "postflowId": { "type": "string", "minLength": 1 }, "itemIds": { "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 500 }, "outcome": { "type": "string", "enum": [ "COMPLETED", "FAILED" ], "default": "COMPLETED" }, "limit": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "outcome": { "type": "string", "enum": [ "COMPLETED", "FAILED" ] }, "counts": { "type": "object", "properties": { "completed": { "type": "integer" }, "failed": { "type": "integer" }, "suppressed": { "type": "integer" }, "skipped": { "type": "integer" } }, "required": [ "completed", "failed", "suppressed", "skipped" ], "additionalProperties": false }, "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] } }, "required": [ "id", "status" ], "additionalProperties": false } }, "skipped": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "anyOf": [ { "type": "string", "enum": [ "NEEDS_ATTENTION", "SUPPRESSED", "HELD", "PENDING_APPROVAL", "READY", "SCHEDULED_FOR_RUN", "IN_PRODUCTION", "COMPLETED", "FAILED", "CANCELLED", "RETURNED", "NOT_SENT" ] }, { "type": "null" } ] }, "reason": { "type": "string", "enum": [ "not_found", "not_ready", "postflow_paused" ] } }, "required": [ "id", "status", "reason" ], "additionalProperties": false } } }, "required": [ "id", "outcome", "counts", "items", "skipped" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "items.write" } }, "/v1/uploads": { "post": { "operationId": "uploads.create", "summary": "Create an upload session with a presigned PUT URL", "tags": [ "Uploads" ], "x-idempotent": true, "x-rate-limit-class": "upload", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "image", "font", "csv", "attachment" ] }, "fileName": { "type": "string", "minLength": 1, "maxLength": 200 }, "contentType": { "type": "string", "minLength": 3, "maxLength": 100 }, "sizeBytes": { "type": "integer", "exclusiveMinimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "licenceConfirmed": { "type": "boolean" } }, "required": [ "kind", "fileName", "contentType", "sizeBytes" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "font", "csv", "attachment" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "UPLOADED", "PROCESSING", "READY", "REJECTED", "EXPIRED" ] }, "rejection": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "resultId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "processedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "method": { "type": "string", "const": "PUT" }, "headers": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "kind", "fileName", "contentType", "sizeBytes", "status", "rejection", "resultId", "expiresAt", "completedAt", "processedAt", "createdAt", "url", "method", "headers" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "A request with this Idempotency-Key is still in progress (idempotency_in_progress)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/uploads/{id}": { "get": { "operationId": "uploads.get", "summary": "Get an upload session", "tags": [ "Uploads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "font", "csv", "attachment" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "UPLOADED", "PROCESSING", "READY", "REJECTED", "EXPIRED" ] }, "rejection": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "resultId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "processedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "fileName", "contentType", "sizeBytes", "status", "rejection", "resultId", "expiresAt", "completedAt", "processedAt", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.read" } }, "/v1/uploads/{id}/complete": { "post": { "operationId": "uploads.complete", "summary": "Complete an upload session (scan and process)", "tags": [ "Uploads" ], "x-rate-limit-class": "upload", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "image", "font", "csv", "attachment" ] }, "fileName": { "type": "string" }, "contentType": { "type": "string" }, "sizeBytes": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "UPLOADED", "PROCESSING", "READY", "REJECTED", "EXPIRED" ] }, "rejection": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "reason": { "type": [ "string", "null" ] } }, "required": [ "code", "reason" ], "additionalProperties": false }, { "type": "null" } ] }, "resultId": { "type": [ "string", "null" ] }, "expiresAt": { "type": "string", "format": "date-time" }, "completedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "processedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "kind", "fileName", "contentType", "sizeBytes", "status", "rejection", "resultId", "expiresAt", "completedAt", "processedAt", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "templates.write" } }, "/v1/webhooks": { "get": { "operationId": "webhooks.list", "summary": "List webhook endpoints", "description": "The organisation's endpoints with their subscription, filters, state and failure streak.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object", "properties": { "postflowId": { "type": "string" }, "postbatchId": { "type": "string" }, "isTest": { "type": "boolean" }, "integrationInstallationId": { "type": "string" } }, "additionalProperties": false }, "active": { "type": "boolean" }, "failureStreak": { "type": "integer" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "EXHAUSTED" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "description", "events", "filters", "active", "failureStreak", "disabledAt", "lastDeliveryAt", "lastStatus", "createdAt", "updatedAt" ], "additionalProperties": false } } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" }, "post": { "operationId": "webhooks.create", "summary": "Create a webhook endpoint", "description": "Registers an https endpoint (at most 20 per organisation) with the event subscription (types, families such as item.*, or *) and optional filters on Postflow, Postbatch and test mode. The response carries the signing secret once.", "tags": [ "Webhooks" ], "parameters": [ { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000 }, "description": { "type": "string", "maxLength": 200 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 60 }, "filters": { "type": "object", "properties": { "postflowId": { "type": "string", "minLength": 1, "maxLength": 40 }, "postbatchId": { "type": "string", "minLength": 1, "maxLength": 40 }, "isTest": { "type": "boolean" }, "integrationInstallationId": { "type": "string", "minLength": 1, "maxLength": 40 } }, "additionalProperties": false }, "active": { "type": "boolean" } }, "required": [ "url", "events" ], "additionalProperties": false } } } }, "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object", "properties": { "postflowId": { "type": "string" }, "postbatchId": { "type": "string" }, "isTest": { "type": "boolean" }, "integrationInstallationId": { "type": "string" } }, "additionalProperties": false }, "active": { "type": "boolean" }, "failureStreak": { "type": "integer" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "EXHAUSTED" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string" } }, "required": [ "id", "url", "description", "events", "filters", "active", "failureStreak", "disabledAt", "lastDeliveryAt", "lastStatus", "createdAt", "updatedAt", "secret" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" } }, "/v1/webhooks/{id}": { "get": { "operationId": "webhooks.get", "summary": "Get a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object", "properties": { "postflowId": { "type": "string" }, "postbatchId": { "type": "string" }, "isTest": { "type": "boolean" }, "integrationInstallationId": { "type": "string" } }, "additionalProperties": false }, "active": { "type": "boolean" }, "failureStreak": { "type": "integer" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "EXHAUSTED" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "description", "events", "filters", "active", "failureStreak", "disabledAt", "lastDeliveryAt", "lastStatus", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" }, "patch": { "operationId": "webhooks.patch", "summary": "Update a webhook endpoint", "description": "Changes the URL, description, subscription, filters or the active flag. Re-enabling a disabled endpoint resets its failure streak and resumes with new events; use replay-missed for the events of the disabled period.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2000 }, "description": { "type": "string", "maxLength": 200 }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 60 }, "filters": { "type": "object", "properties": { "postflowId": { "type": "string", "minLength": 1, "maxLength": 40 }, "postbatchId": { "type": "string", "minLength": 1, "maxLength": 40 }, "isTest": { "type": "boolean" }, "integrationInstallationId": { "type": "string", "minLength": 1, "maxLength": 40 } }, "additionalProperties": false }, "active": { "type": "boolean" } }, "additionalProperties": false } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "url": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "object", "properties": { "postflowId": { "type": "string" }, "postbatchId": { "type": "string" }, "isTest": { "type": "boolean" }, "integrationInstallationId": { "type": "string" } }, "additionalProperties": false }, "active": { "type": "boolean" }, "failureStreak": { "type": "integer" }, "disabledAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastDeliveryAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lastStatus": { "anyOf": [ { "type": "string", "enum": [ "SUCCEEDED", "FAILED", "EXHAUSTED" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "description", "events", "filters", "active", "failureStreak", "disabledAt", "lastDeliveryAt", "lastStatus", "createdAt", "updatedAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" }, "delete": { "operationId": "webhooks.remove", "summary": "Delete a webhook endpoint", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "204": { "description": "No content" }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" } }, "/v1/webhooks/{id}/deliveries": { "get": { "operationId": "webhooks.deliveries", "summary": "Delivery log of an endpoint", "description": "Deliveries newest first with a cursor: the event, the origin (dispatch, replay, test), the attempt count, status, last response code, duration, error, the next attempt and the attempt history with the payload preview.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "EXHAUSTED" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 200 } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "origin": { "type": "string", "enum": [ "DISPATCH", "REPLAY", "TEST" ] }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "EXHAUSTED" ] }, "responseCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ] }, "responseCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationMs": { "type": "integer" }, "error": { "type": [ "string", "null" ] } }, "required": [ "attempt", "at", "status", "responseCode", "durationMs", "error" ], "additionalProperties": false } }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "organisationId": { "type": "string" }, "isTest": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "type", "version", "createdAt", "organisationId", "isTest", "data" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpointId", "eventId", "eventType", "origin", "attempt", "status", "responseCode", "durationMs", "error", "nextAttemptAt", "deliveredAt", "attempts", "payload", "createdAt" ], "additionalProperties": false } }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" } }, "/v1/webhooks/{id}/deliveries/{deliveryId}/replay": { "post": { "operationId": "webhooks.replay", "summary": "Replay a delivery", "description": "Creates a new delivery of the same event to the endpoint, starting at attempt 1.", "tags": [ "Webhooks" ], "parameters": [ { "name": "deliveryId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "origin": { "type": "string", "enum": [ "DISPATCH", "REPLAY", "TEST" ] }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "EXHAUSTED" ] }, "responseCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ] }, "responseCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationMs": { "type": "integer" }, "error": { "type": [ "string", "null" ] } }, "required": [ "attempt", "at", "status", "responseCode", "durationMs", "error" ], "additionalProperties": false } }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "organisationId": { "type": "string" }, "isTest": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "type", "version", "createdAt", "organisationId", "isTest", "data" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpointId", "eventId", "eventType", "origin", "attempt", "status", "responseCode", "durationMs", "error", "nextAttemptAt", "deliveredAt", "attempts", "payload", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" } }, "/v1/webhooks/{id}/replay-missed": { "post": { "operationId": "webhooks.replayMissed", "summary": "Replay the events missed while disabled", "description": "Creates deliveries for the subscribed events since the endpoint was disabled (or since the given moment) that have no delivery yet; at most 500 per call.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" } }, "additionalProperties": false, "default": {} } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "since": { "type": "string", "format": "date-time" }, "created": { "type": "integer" } }, "required": [ "since", "created" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Validation failed", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" } }, "/v1/webhooks/{id}/test": { "post": { "operationId": "webhooks.test", "summary": "Send a test event", "description": "Delivers a webhook.test envelope to the endpoint through the normal delivery path.", "tags": [ "Webhooks" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/OrganisationId" } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "endpointId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "origin": { "type": "string", "enum": [ "DISPATCH", "REPLAY", "TEST" ] }, "attempt": { "type": "integer" }, "status": { "type": "string", "enum": [ "PENDING", "SUCCEEDED", "FAILED", "EXHAUSTED" ] }, "responseCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationMs": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "error": { "type": [ "string", "null" ] }, "nextAttemptAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "deliveredAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer" }, "at": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "SUCCEEDED", "FAILED" ] }, "responseCode": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "durationMs": { "type": "integer" }, "error": { "type": [ "string", "null" ] } }, "required": [ "attempt", "at", "status", "responseCode", "durationMs", "error" ], "additionalProperties": false } }, "payload": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "item.created", "item.needs_attention", "item.held", "item.ready", "item.pending_approval", "item.scheduled", "item.in_production", "item.handed_to_carrier", "item.completed", "item.returned", "item.not_sent", "item.failed", "item.cancelled", "item.suppressed", "postbatch.validated", "postbatch.approved", "postbatch.scheduled", "postbatch.completed", "postbatch.cancelled", "import.completed", "import.failed", "template.published", "preview.ready", "qr.scanned", "run.cutoff_reached", "run.rendered", "run.handed_to_printer", "webhook.disabled", "webhook.test", "balance.low", "invoice.issued" ] }, "version": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" }, "organisationId": { "type": "string" }, "isTest": { "type": "boolean" }, "data": { "type": "object", "properties": {}, "additionalProperties": true } }, "required": [ "id", "type", "version", "createdAt", "organisationId", "isTest", "data" ], "additionalProperties": false }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "endpointId", "eventId", "eventType", "origin", "attempt", "status", "responseCode", "durationMs", "error", "nextAttemptAt", "deliveredAt", "attempts", "payload", "createdAt" ], "additionalProperties": false } } } }, "401": { "description": "Authentication required or API key invalid", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Permission or scope missing, organisation suspended", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "Rate limited for this API key and class; wait Retry-After seconds", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } } }, "default": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "security": [ { "apiKey": [] }, { "session": [] } ], "x-permission": "webhooks.manage" } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Organisation API key (pb_live_… or pb_test_…)." }, "session": { "type": "apiKey", "in": "cookie", "name": "pb.session_token", "description": "Portal session cookie; requests also carry X-Organisation-Id and, for mutations, X-CSRF-Token." }, "adminSession": { "type": "apiKey", "in": "cookie", "name": "pba.session_token", "description": "Admin console session cookie." } }, "parameters": { "OrganisationId": { "name": "X-Organisation-Id", "in": "header", "required": false, "description": "Required with a session cookie; implied by an API key.", "schema": { "type": "string" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "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).", "schema": { "type": "string", "maxLength": 255 } } }, "headers": { "RequestId": { "description": "Correlation id echoed on every response; quote it to support.", "schema": { "type": "string" } }, "RateLimitLimit": { "description": "Requests per minute allowed for this API key and class (API-007).", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the budget resets.", "schema": { "type": "integer" } }, "RetryAfter": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "schemas": { "FieldError": { "type": "object", "required": [ "field", "code", "message" ], "properties": { "field": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "Problem": { "type": "object", "description": "RFC 9457 problem details with a stable code (API-006).", "required": [ "type", "title", "status", "code" ], "properties": { "type": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "status": { "type": "integer" }, "code": { "type": "string", "enum": [ "authentication_required", "api_key_invalid", "api_key_revoked", "insufficient_scope", "permission_denied", "organisation_suspended", "csrf_failed", "validation_failed", "idempotency_key_reused", "idempotency_in_progress", "rate_limited", "not_found", "draft_conflict", "template_in_use", "template_archived", "folder_not_empty", "variable_name_conflict", "product_not_entitled", "feature_not_entitled", "postflow_limit_reached", "allowance_exceeded", "postflow_archived", "item_locked_for_production", "invalid_item_transition", "invalid_postbatch_transition", "insufficient_balance", "credit_limit_reached", "import_too_large", "import_invalid_file", "mapping_incomplete", "destination_not_supported", "integration_disabled", "blocked_in_support_session", "ticket_closed", "upload_rejected", "asset_in_use", "still_referenced", "base_template_violation", "upload_too_large", "upload_incomplete", "image_url_not_allowed", "item_render_failed", "mfa_enrolment_required", "admin_permission_required", "step_up_required", "last_super_admin", "last_owner", "organisation_context_required", "vies_unavailable", "invitation_expired", "invitation_email_mismatch", "invitation_pending", "already_member", "product_activation_blocked", "specification_immutable", "internal_error", "service_unavailable" ] }, "detail": { "type": "string" }, "instance": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FieldError" } } } } }, "responses": { "Problem": { "description": "Error (RFC 9457 problem details)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "x-error-codes": [ { "code": "authentication_required", "status": 401, "title": "Authentication required" }, { "code": "api_key_invalid", "status": 401, "title": "API key invalid" }, { "code": "api_key_revoked", "status": 401, "title": "API key revoked" }, { "code": "insufficient_scope", "status": 403, "title": "Insufficient scope" }, { "code": "permission_denied", "status": 403, "title": "Permission denied" }, { "code": "organisation_suspended", "status": 403, "title": "Organisation suspended" }, { "code": "csrf_failed", "status": 403, "title": "Cross-site request refused" }, { "code": "validation_failed", "status": 422, "title": "Validation failed" }, { "code": "idempotency_key_reused", "status": 422, "title": "Idempotency key reused with a different body" }, { "code": "idempotency_in_progress", "status": 409, "title": "Request with this idempotency key in progress" }, { "code": "rate_limited", "status": 429, "title": "Rate limited" }, { "code": "not_found", "status": 404, "title": "Not found" }, { "code": "draft_conflict", "status": 412, "title": "Draft was modified elsewhere" }, { "code": "template_in_use", "status": 409, "title": "Template in use" }, { "code": "template_archived", "status": 409, "title": "Template archived" }, { "code": "folder_not_empty", "status": 409, "title": "Folder not empty" }, { "code": "variable_name_conflict", "status": 422, "title": "Variable names conflict" }, { "code": "product_not_entitled", "status": 403, "title": "Product not entitled" }, { "code": "feature_not_entitled", "status": 403, "title": "Feature not entitled" }, { "code": "postflow_limit_reached", "status": 403, "title": "Postflow limit reached" }, { "code": "allowance_exceeded", "status": 403, "title": "Allowance exceeded" }, { "code": "postflow_archived", "status": 409, "title": "Postflow archived" }, { "code": "item_locked_for_production", "status": 409, "title": "Item locked for production" }, { "code": "invalid_item_transition", "status": 409, "title": "Invalid item transition" }, { "code": "invalid_postbatch_transition", "status": 409, "title": "Invalid Postbatch transition" }, { "code": "insufficient_balance", "status": 402, "title": "Insufficient balance" }, { "code": "credit_limit_reached", "status": 402, "title": "Credit limit reached" }, { "code": "import_too_large", "status": 413, "title": "Import too large" }, { "code": "import_invalid_file", "status": 422, "title": "Import file invalid" }, { "code": "mapping_incomplete", "status": 422, "title": "Mapping incomplete" }, { "code": "destination_not_supported", "status": 422, "title": "Destination not supported" }, { "code": "integration_disabled", "status": 403, "title": "Integration disabled" }, { "code": "blocked_in_support_session", "status": 403, "title": "Blocked in support session" }, { "code": "ticket_closed", "status": 409, "title": "Ticket closed" }, { "code": "upload_rejected", "status": 422, "title": "Upload rejected" }, { "code": "asset_in_use", "status": 409, "title": "Asset in use" }, { "code": "still_referenced", "status": 409, "title": "Still referenced" }, { "code": "base_template_violation", "status": 422, "title": "Base template rules broken" }, { "code": "upload_too_large", "status": 413, "title": "Upload too large" }, { "code": "upload_incomplete", "status": 409, "title": "Upload not completed" }, { "code": "image_url_not_allowed", "status": 422, "title": "Image URL not allowed" }, { "code": "item_render_failed", "status": 422, "title": "Item could not be rendered" }, { "code": "mfa_enrolment_required", "status": 403, "title": "Second factor enrolment required" }, { "code": "admin_permission_required", "status": 403, "title": "Console permission required" }, { "code": "step_up_required", "status": 403, "title": "A fresh second factor code is required" }, { "code": "last_super_admin", "status": 409, "title": "The last Super admin cannot be disabled, removed or demoted" }, { "code": "last_owner", "status": 409, "title": "The last Owner cannot be removed or demoted" }, { "code": "organisation_context_required", "status": 400, "title": "Organisation header required" }, { "code": "vies_unavailable", "status": 503, "title": "VAT validation service unavailable" }, { "code": "invitation_expired", "status": 410, "title": "Invitation expired or withdrawn" }, { "code": "invitation_email_mismatch", "status": 403, "title": "Invitation was sent to another email address" }, { "code": "invitation_pending", "status": 409, "title": "An invitation for this email is already pending" }, { "code": "already_member", "status": 409, "title": "Already a member of this organisation" }, { "code": "product_activation_blocked", "status": 409, "title": "Product activation blocked" }, { "code": "specification_immutable", "status": 409, "title": "Specification version is immutable" }, { "code": "internal_error", "status": 500, "title": "Internal error" }, { "code": "service_unavailable", "status": 503, "title": "Service unavailable" } ], "x-warning-codes": [ "address_invalid", "postal_code_invalid", "house_number_missing", "city_missing", "country_not_supported", "destination_not_supported", "variable_missing", "variable_type_invalid", "variable_too_long", "image_fetch_failed", "image_resolution_low", "text_overflow", "expression_invalid", "late_delivery_expected", "waiting_for_funds", "suppressed", "carrier_codes_missing", "excluded_from_run" ] }