{ "swagger": "2.0", "info": { "version": "1.4.0", "description": "Welcome to the **Binect REST API** – the interface for sending documents as **physical mail** through mail service providers in Germany – **not exclusively via Deutsche Post**. Your documents are printed, enveloped, franked and delivered by our production partners.\n\n## Environments\n\n| Environment | URL | Purpose |\n| --- | --- | --- |\n| **Production** | https://app.binect.de | Real, chargeable dispatch |\n| **Test** | https://test-app.binect.de | Free of charge – **simulates** dispatch |\n\n- The two environments have **separate user management** – you need a **dedicated account** in each. Create accounts via the login page – [Production](https://app.binect.de/index.jsp?id=login) · [Test](https://test-app.binect.de/index.jsp?id=login).\n- The test environment may run a **more recent version** than production; **handling and response behaviour** are intentionally identical, however.\n\n## Sending in two steps\n\n1. **[`POST /documents`](#op:documents:uploadDocument:post:/documents)** – upload a document and have it validated.\n2. **[`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings)** – hand an uploaded, valid document over for dispatch.\n\n## … or in a single step\n\n- **[`POST /sendings/document`](#op:sendings:uploadAndSendDocument:post:/sendings/document)** – shortcut: upload and, on successful validation, dispatch **directly**.\n\n**Editing & lifecycle:** While a document has not yet been released for dispatch, it can be modified via `/documents` (options, transformation, cover page, attachments) or deleted. Once successfully released for dispatch, `/sendings` is responsible.\n\n## Supported postal products\n\n- **Registered mail / Einschreiben** (Deutsche Post): Standard, Einwurf (drop-in), International – trackable all the way to the mailbox\n- **PremiumAdress** (Deutsche Post): Report, Basic *(paid activation required)*\n- **Franked** dispatch\n- **DV-prepaid** dispatch (DV-Freimachung – fast, maximum feature set)\n\n## Document requirements\n\n- Documents are transmitted as **PDF in Base64** format.\n- **PDF** and **PostScript (PS)** are allowed – **PDF preferred**. Maximum file size: **20 MB** (effective value: `maxUploadSize` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)).\n- Recommended print specs: **PDF/A-2b**, **embedded fonts**, **CMYK** colour space.\n- Sample letters: [DOCX template](/downloadFile?fileId=4) · [ODT template](/downloadFile?fileId=3) – please transmit as PDF (Base64).\n- Layout templates for address and exclusion zones: [download template](/downloadFile?fileId=24).\n- A document may contain at most **192 sheets** (192 pages simplex, 384 pages duplex).\n- **Production in Austria:** on request, customers from Austria can have documents produced in Austria together with Binect GmbH (`productionCountry: AT`).\n- **Addressing:** place the recipient address in the **address field** (visible in the window for window envelopes); keep the **exclusion zones** (franking, processing codes) clear. For exact positions see the [layout template](/downloadFile?fileId=24) and the FAQ [„Welche Datei- und Formatanforderungen gelten für meinen Brief?“](/index.jsp?id=faq#faq_5). If no valid address is detected in the correct area, it can be corrected via a transformation or a cover page.\n\n## Addressing & exclusion zones\n\nAll measurements are taken from the **top-left corner** of the page. The recipient and sender address must be positioned so that they are fully visible in the **window of a DIN-lang envelope**; the exclusion zones must be kept clear.\n\n| Area | Width | Height | From left | From top |\n| --- | --- | --- | --- | --- |\n| Recipient address field | 85 mm | 21 mm | 20 mm | 69 mm |\n| Sender address field | 85 mm | 5.5 mm | 20 mm | 45 mm |\n| DV exclusion zone | 85 mm | 17.5 mm | 20 mm | 51 mm |\n\n**DV validation:** Since **2022-09-27**, DV validation is the platform's new standard. The existing address and exclusion zones remain valid; for DV compatibility, **additionally** keep the DV exclusion zone listed above clear – it must contain **no content (text or images/graphics)**, because the **DV franking** is printed into it. [Download the layout template](/downloadFile?fileId=24).\n\n## Processing & deadlines\n\n- Hand-over to production by default at **14:30**; **cancellations** are possible until shortly before.\n- **Status queries** are only meaningful from **05:00 on the following day** – and only if the sending made the **14:30 dispatch window**, because the dispatch status is updated only then.\n- **Maintenance window:** every **Tuesday, 21:00–23:00**.\n\n## Custom attributes\n\n- Pass your **internal reference id** in the **`externalReferenceId`** field (ideally a UUID) – this makes the document findable later via **`GET /documents/findByExternalReferenceId`**.\n- **Cost-center billing?** Possible with individual invoicing via the **`tenantId`** field.\n\n## Validation & correction\n\n- Documents that **fail validation** can often be salvaged – e.g. via the **transformations** endpoint (move & scale) or the **cover-page** function – turning them into a dispatchable document.\n\n## Error responses\n\n- Errors come with the matching **HTTP status** and a **plain-text** body (`Content-Type: text/plain;charset=UTF-8`), e.g. `Not Found: Document 4711 doesn't exist.` Evaluate the **HTTP status** – the text is meant for display and may change.\n- Where a **Binect error code** applies, it is also sent in the **`X-Error-Code`** header (e.g. `X-Error-Code: 4404`). The meaning of all codes, in German and English: [`/binectapi/error-codes.json`](/binectapi/error-codes.json).\n- Successful responses carrying data are **JSON**. If `Accept` asks exclusively for another format (e.g. only `text/plain`), the API answers **`406`** (code `4406`). `Accept: application/json` or `*/*` is always correct.\n- If the sign-in cannot be verified temporarily, the API answers **`503`** with a **`Retry-After`** header (code `4503`). This is not a fault of your request: retry it after the number of seconds given there.\n- After repeated **wrong passwords** from your address, the API answers **`429`** with a **`Retry-After`** header (code `4429`) without checking the password. Clients that send the correct password from an address that has signed in successfully before are not slowed down. If a login is under heavy attack, the API rejects addresses that have never signed in successfully for up to 24 hours. API keys are never affected. Check the password and retry only after the number of seconds given there – or sign in with an API key.\n\n## Error handling on upload (HTTP 500)\n\n- On a **`500`** during upload, **always assume the document may nonetheless have arrived**.\n- **Recommendation:** send a unique **`externalReferenceId`** on upload and, on error, query it via **`GET /documents/findByExternalReferenceId`**:\n - **match** → the document arrived (do not re-upload).\n - **no match** → the document did **not** reach the service → re-upload.\n\n## Example code: `POST /sendings/document` (upload + send in one step)\n\nThe default URL is the **Test environment** (`https://test-app.binect.de/binectapi/v1`); for Production use `https://app.binect.de/binectapi/v1`. Authentication via **API key** (recommended, `Authorization: Bearer `) or **HTTP Basic** (email + password) - the examples below use Basic, the credentials are **placeholders**.\n\n
\nShow example code\n

Bash (curl)

\n
# Default: Testumgebung. Produktion: https://app.binect.de/binectapi/v1\nBASE_URL=\"https://test-app.binect.de/binectapi/v1\"\nEMAIL=\"ihre-email@example.com\"\nPASSWORD=\"ihr-passwort\"\nB64=$(base64 -w0 brief.pdf)        # macOS: base64 -i brief.pdf\ncurl -s -u \"$EMAIL:$PASSWORD\" -H \"Content-Type: application/json\" \\\n  -X POST \"$BASE_URL/sendings/document\" -d @- <<JSON\n{\n  \"content\": { \"filename\": \"brief.pdf\", \"content\": \"$B64\" },\n  \"options\": { \"simplex\": true, \"color\": false, \"envelope\": \"DINLANG\", \"franking\": \"DV_FRANKING\", \"product\": \"NORMAL\" },\n  \"tenantId\": \"kostenstelle-4711\",\n  \"externalReferenceId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\"\n}\nJSON
\n

Python (requests)

\n
import base64, requests\nBASE_URL = \"https://test-app.binect.de/binectapi/v1\"  # Prod: https://app.binect.de/binectapi/v1\nEMAIL, PASSWORD = \"ihre-email@example.com\", \"ihr-passwort\"\nwith open(\"brief.pdf\", \"rb\") as fh:\n    content = base64.b64encode(fh.read()).decode()\nresp = requests.post(\n    f\"{BASE_URL}/sendings/document\",\n    auth=(EMAIL, PASSWORD),\n    json={\n        \"content\": {\"filename\": \"brief.pdf\", \"content\": content},\n        \"options\": {\"simplex\": True, \"color\": False, \"envelope\": \"DINLANG\",\n                    \"franking\": \"DV_FRANKING\", \"product\": \"NORMAL\"},\n        \"tenantId\": \"kostenstelle-4711\",\n        \"externalReferenceId\": \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n    },\n)\nprint(resp.status_code, resp.json())
\n

JavaScript (Node 18+, fetch)

\n
import { readFile } from \"node:fs/promises\";\nconst BASE_URL = \"https://test-app.binect.de/binectapi/v1\"; // Prod: https://app.binect.de/binectapi/v1\nconst EMAIL = \"ihre-email@example.com\", PASSWORD = \"ihr-passwort\";\nconst content = (await readFile(\"brief.pdf\")).toString(\"base64\");\nconst auth = \"Basic \" + Buffer.from(`${EMAIL}:${PASSWORD}`).toString(\"base64\");\nconst resp = await fetch(`${BASE_URL}/sendings/document`, {\n  method: \"POST\",\n  headers: { \"Content-Type\": \"application/json\", Authorization: auth },\n  body: JSON.stringify({\n    content: { filename: \"brief.pdf\", content },\n    options: { simplex: true, color: false, envelope: \"DINLANG\", franking: \"DV_FRANKING\", product: \"NORMAL\" },\n    tenantId: \"kostenstelle-4711\",\n    externalReferenceId: \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n  }),\n});\nconsole.log(resp.status, await resp.json());
\n

PHP (curl)

\n
<?php\n$baseUrl  = \"https://test-app.binect.de/binectapi/v1\"; // Prod: https://app.binect.de/binectapi/v1\n$email    = \"ihre-email@example.com\";\n$password = \"ihr-passwort\";\n$content = base64_encode(file_get_contents(\"brief.pdf\"));\n$payload = json_encode([\n  \"content\"    => [\"filename\" => \"brief.pdf\", \"content\" => $content],\n  \"options\"    => [\"simplex\" => true, \"color\" => false, \"envelope\" => \"DINLANG\",\n                   \"franking\" => \"DV_FRANKING\", \"product\" => \"NORMAL\"],\n  \"tenantId\" => \"kostenstelle-4711\",\n  \"externalReferenceId\" => \"3f2504e0-4f89-41d3-9a0c-0305e82c3301\",\n]);\n$ch = curl_init(\"$baseUrl/sendings/document\");\ncurl_setopt_array($ch, [\n  CURLOPT_POST           => true,\n  CURLOPT_RETURNTRANSFER => true,\n  CURLOPT_USERPWD        => \"$email:$password\",\n  CURLOPT_HTTPHEADER     => [\"Content-Type: application/json\"],\n  CURLOPT_POSTFIELDS     => $payload,\n]);\n$resp = curl_exec($ch);\necho curl_getinfo($ch, CURLINFO_HTTP_CODE) . \"\\n\" . $resp . \"\\n\";
\n
\n\n## Authentication, billing & notes\n\n- **Authentication:** with an **API key** (recommended) or with HTTP Basic using **e-mail + password**. You create API keys in the customer portal under **Mein Konto → API-Keys** (My account → API keys). There you also choose per login what the REST API accepts: the password only (default), password and API key, or API keys only. Send **exactly one** sign-in per request – the key as `Authorization: Bearer `, as `X-API-Key: ` or, for clients that only support Basic, as the password (the user name is ignored; we recommend your e-mail address). A key stays valid when you change your password or e-mail address. **Never** send a key as a query parameter in the URL. In Swagger UI, authorize only one of the three methods. Keys are created, deactivated and deleted only in the customer portal under **Mein Konto → API-Keys**; the REST API does not manage keys. [`GET /accounts/authentication`](#op:accounts:getAuthentication:get:/accounts/authentication) shows how a request was signed in and which client IP address the server sees.\n- **Payment:** the default is **prepaid** (PayPal, credit card, Sofortüberweisung). On request, an account can be enabled for **invoicing (on account)**. Cost-center billing via the `tenantId` field (see above).\n- **Sales partners:** partner options can be discussed with sales ([info@binect.de](mailto:info@binect.de)).\n- **Notifications:** you must **poll actively** for new letter states (status endpoints). There is currently **no webhook interface**, though one may be added in the future.\n\n## Support & contact\n\n- **Technical questions / issues:** [kontakt@binect.de](mailto:kontakt@binect.de)\n- **Integration support / quote:** Binect Sales – [info@binect.de](mailto:info@binect.de)", "title": "Binect REST API", "termsOfService": "/downloadFile?fileId=2", "contact": { "name": "kontakt@binect.de" } }, "basePath": "/binectapi/v1", "securityDefinitions": { "basicAuth": { "type": "basic", "description": "HTTP Basic authentication with your e-mail address and password. Clients that only support Basic can send an API key as the password instead: the user name is then ignored (we recommend your e-mail address). A password beginning with `bnct_` is treated as an API key. Send exactly one sign-in per request: two different `Authorization` headers, or `Authorization` together with an API key in `X-API-Key`, are rejected with `400` and error code `44015`. For logins that only accept API keys, the password is rejected with `403` and error code `44034`; if the sign-in cannot be verified temporarily, the API answers `503` with `Retry-After` (error code `4503`). After repeated wrong passwords from the same address, the API answers `429` with `Retry-After` (error code `4429`) without checking the password." }, "bearerAuth": { "type": "apiKey", "in": "header", "name": "Authorization", "description": "API key in the `Authorization` header: `Authorization: Bearer ` (recommended). In Swagger UI, paste the key itself (`bnct_…`); `Bearer ` is added automatically. You create API keys in the customer portal under **Mein Konto → API-Keys** (My account → API keys); the full key is shown only once, when it is created. An invalid, deactivated or expired key is rejected with `401` and error code `44012`, `44013` or `44014`. If the key cannot be verified temporarily (a short disruption or too many simultaneous checks), the API answers `503` with `Retry-After` (error code `4503`)." }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "API key in the `X-API-Key` header: `X-API-Key: ` – the easiest way in Swagger UI (enter just the key). Use it on its own: together with an `Authorization` header the request is rejected with `400` and error code `44015`. If the key cannot be verified temporarily (a short disruption or too many simultaneous checks), the API answers `503` with `Retry-After` (error code `4503`)." } }, "security": [ { "basicAuth": [] }, { "bearerAuth": [] }, { "apiKeyHeader": [] } ], "tags": [ { "name": "documents", "description": "Upload, validate, edit and query documents (before dispatch release)." }, { "name": "status", "description": "Status queries for documents and sendings." }, { "name": "corrections", "description": "Corrections to documents: transformations and cover page." }, { "name": "attachments", "description": "Manage attachments (the attachment pool and per-document attachments)." }, { "name": "sendings", "description": "Dispatch release, cancellation and dispatch status." }, { "name": "regmails", "description": "Registered mail: status and tracking." }, { "name": "accounts", "description": "Account: balance, personal data, default shipping options, coworkers, journal, API keys and sign-in." }, { "name": "invoices", "description": "Invoices and their transactions." } ], "externalDocs": { "description": "AI agents & integration overview (llms.txt)", "url": "/llms.txt" }, "paths": { "/documents": { "delete": { "tags": [ "documents" ], "description": "Deletes several documents that have **not yet been handed over for dispatch**, in one request – the bulk variant of `DELETE /documents/{documentID}`, whose behaviour is unchanged.\n\nEvery id is attempted **on its own**; one id that cannot be deleted does not stop the others and leaves its letter untouched at that moment. The answer is always `200` with one entry per **distinct** requested id, in request order – duplicate ids are collapsed, so **match entries by `id`, never by position**. `deleted` says whether it was deleted, `error` names the reason if it was not: the same error codes the single-document variant returns (`4404` unknown or already deleted, `4403` other account, `44091` state does not permit deletion, `4500` hard error), plus `44092`, which only this bulk variant returns, for a serial letter blocked by its individual letters. **Check every entry; the HTTP status says nothing about the individual results.**\n\nDeleting a serial letter deletes its individual letters as well; `deletedChildren` gives their number without listing them. If an individual letter is requested together with its serial letter, the serial letter is handled first and the individual letter reports `deleted: true` with `deletedAsChildOf` – not `4404`. It also works the other way round: deleting the **last** remaining individual letter of a serial letter deletes the serial letter with it, even when the serial letter itself was not requested – it then has no entry of its own in the answer. The operation is **not atomic**: a partial result is real and is not rolled back.\n\nPass the ids as repeated parameters (`?documentIds=17&documentIds=18`); a comma-separated value is **not** accepted. At most `maxDelete` ids per request (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits), default 250) – above that `413` with error code `44008`, and nothing is deleted.", "produces": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "query", "required": true, "type": "array", "collectionFormat": "multi", "items": { "type": "integer", "format": "int32" }, "description": "The document ids to delete, as repeated parameters." } ], "responses": { "200": { "description": "Successful response – one entry per requested id. Individual ids may still have been rejected; check `deleted` and `error` per entry.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentDeletionStatus" } } }, "400": { "description": "Bad Request – `documentIds` is missing, empty, or carries an empty value (`?documentIds=`). Error code `4400`. Nothing was deleted." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Request Entity Too Large – more ids than `maxDelete` from `GET /accounts/limits` allows (default 250). Error code `44008`. Nothing was deleted; split the list into blocks." } }, "operationId": "deleteDocuments" }, "post": { "tags": [ "documents" ], "description": "Uploads a new document. The document is a **single letter** or a **serial letter** and contains a valid address in the address field while respecting the exclusion zones.\n\n**File formats:** **PDF** and **PostScript (PS)** are allowed – **PDF is preferred**. PDFs should conform to **PDF/A-2b** (embedded fonts, CMYK colour space). Maximum file size: **20 MB** (effective value: `maxUploadSize` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)).\n\n**Transfer:** The content is passed **Base64-encoded** in the `content` field.\n\n**Validation:** The document is validated. If validation fails, an optional correction (transformation, cover page) is offered where possible. The response contains a valid document or an `error` object.\n\n**Note:** The document is normalized for print production; we recommend a visual check via `GET /documents/{documentID}/pdf`.\n\n**Tip:** For fast dispatch with the maximum feature set, use **DV-Freimachung** (the modern franking method).\n\n**Status after upload** (`status.code` → `status.text`):\n- **2** – `ready to ship` (de `versandbereit`)\n- **7** – `faulty` (de `fehlerhaft`)\n- **8** – `delivered` (de `zugestellt`) – registered mail only, final state\n- **9** – `returned to sender` (de `zurückgelaufen`) – registered mail only, final state\n\n**Reliability:** On HTTP `500` the upload may still have succeeded. Send an `externalReferenceId` and, in that case, verify via `GET /documents/findByExternalReferenceId` before re-uploading (a match means it arrived).", "parameters": [ { "name": "upload", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "options": { "$ref": "#/definitions/Options" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } }, "tenantId": { "type": "string", "maxLength": 32, "example": "kostenstelle-4711", "description": "Your internal customer/tenant number for this order (max. 32 characters). It is stored on the order and forwarded to production. Replaces the former `tenant` custom attribute. Control characters (e.g. tab, line break), invisible formatting characters and special spaces (e.g. non-breaking space) are rejected with HTTP 400; the error names the position and the character. Legacy custom attributes containing such characters are not mapped." }, "externalReferenceId": { "type": "string", "maxLength": 64, "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "description": "Your internal reference id for this order (max. 64 characters); a **UUID** is the ideal format. Searchable via `GET /documents/findByExternalReferenceId`. Replaces the former `documentID` custom attribute. Control characters (e.g. tab, line break), invisible formatting characters and special spaces (e.g. non-breaking space) are rejected with HTTP 400; the error names the position and the character. Legacy custom attributes containing such characters are not mapped." }, "externalReferenceIdUnique": { "type": "boolean", "default": false, "description": "Opt-in duplicate protection. If `true`, the upload is rejected when another of your orders already carries this `externalReferenceId` (guards against accidental double submissions)." }, "splitParams": { "description": "For a serial letter, defines how it is split into individual letters. Use either `splitToken` or `splitAfterNumberOfPages`, not both.", "type": "object", "properties": { "splitToken": { "type": "string", "description": "Text token at which the serial letter is split into individual letters." }, "splitAfterNumberOfPages": { "type": "integer", "format": "int32", "description": "The serial letter is split every N pages." } }, "example": { "splitToken": "Sehr geehrte" } }, "responseFormat": { "$ref": "#/definitions/ResponseFormatEnum" } }, "example": { "content": { "filename": "musterbrief.pdf", "content": "" }, "tenantId": "kostenstelle-4711", "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } } ], "responses": { "200": { "description": "Document created – may be erroneous (check `status`; on code 7 see `error`).", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Request Entity Too Large – the file exceeds the maximum upload size (20 MB, see `maxUploadSize` in `GET /accounts/limits`; for a serial letter with `splitParams` 60 MB, see `maxSerialLetterUploadSize`)." } }, "operationId": "uploadDocument" }, "get": { "tags": [ "documents" ], "description": "Returns documents **before dispatch release**, each with its full details (recipient, options, attachments, price) - the status query plus everything else known about the letter.\n\nCovered are letters still being validated and letters ready to ship:\n- **1** - `being created` (de `wird erstellt`) - upload accepted, validation still running\n- **2** - `ready to ship` (de `versandbereit`)\n\nNot covered: **faulty** letters (code 7) - use `GET /documents/errors` - and everything after the dispatch release, which `GET /sendings` answers.\n\nOnly the uploaded letters themselves are returned; the individual letters of a serial letter are not part of this list. Use `GET /documents/status` or `GET /status` if you need them.\n\nBecause every entry carries the full document, the response grows quickly. Without `limit` the amount is capped at `maxRead` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) (default 500); beyond it the answer is `413` with error code `44007`. For plain status polling use `GET /documents/status` or `GET /status` - orders of magnitude smaller, and with a much higher cap.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "The documents before dispatch release, with all their details.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Content Too Large - more readable documents than `maxRead` from `GET /accounts/limits` allows (default 500), or `limit` above it. Error code `44007`. Use `limit` and `offset`." } }, "operationId": "listShippableDocuments" } }, "/documents/status": { "get": { "tags": [ "documents", "status" ], "description": "Returns the status of documents **before dispatch release** - `documentID` plus `status` (`code` and `text`), no document details.\n\nEspecially useful after an upload with `responseFormat` = `SHORT`: the upload then returns immediately, without the validation result, and validation runs afterwards. This endpoint retrieves the outcome later.\n\nStatus codes in this phase:\n- **1** - `being created` (de `wird erstellt`) - the letter is waiting for validation, being validated, being split into individual letters (serial letter), or is having attachments added\n- **2** - `ready to ship` (de `versandbereit`)\n- **7** - `faulty` (de `fehlerhaft`)\n\n`documentIds` changes the behaviour:\n- **with** `documentIds`: exactly the requested documents, in **any** state - an id-based query is not bound to the phase. Ids that cannot be read are omitted; `404` only if none of them can be read.\n- **without** `documentIds`: all documents of the account in this phase, including the individual letters of a serial letter (they can be dispatched individually through this API). Drafts and letters still being edited in the web portal never appear - both exist only in the web interface.\n\nUse `limit` and `offset` to page. Without `limit` the amount is capped at `maxReadStatus` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) (default 5000); beyond it the answer is `413` with error code `44007`.\n\n**Until when it delivers:** without `documentIds` a letter leaves this answer at the dispatch release - `GET /sendings/status` answers it from then on. `GET /status` spans both phases and does not have this break.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "413": { "description": "Content Too Large - more readable documents than `maxReadStatus` from `GET /accounts/limits` allows (default 5000), or `limit` above it. Error code `44007`. Use `limit` and `offset`." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found - none of the ids given in `documentIds` can be read for this account. Without `documentIds` this code does not occur; an account with no letters in this phase receives an empty list with 200." } }, "operationId": "listDocumentValidationStatus" } }, "/documents/errors": { "get": { "tags": [ "documents" ], "description": "Returns all uploaded, **erroneous** documents.\n\nErroneous documents have `status.code` **7** – `faulty` (de `fehlerhaft`). Check the error message(s) in the `error` field and the preview via `GET /documents/{documentID}/pdf` or `/png`.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "A list of erroneous documents.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Content Too Large - more readable documents than `maxRead` from `GET /accounts/limits` allows (default 500), or `limit` above it. Error code `44007`. Use `limit` and `offset`." } }, "operationId": "listFaultyDocuments" } }, "/documents/findbyAttributes": { "get": { "tags": [ "documents" ], "description": "Returns all uploaded documents that are tagged with the given attributes.\n\nAt least one `key`/`value` pair is required. `key` and `value` are matched **by position** (`key[0]` pairs with `value[0]`, etc.); both arrays must therefore contain the **same number** of entries. Keys and values are cleaned exactly like when storing (control and invisible formatting characters removed, tabs/line breaks/special spaces become a space), so a search value with a trailing line break still finds the stored value.", "parameters": [ { "name": "key", "in": "query", "required": true, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "name": "value", "in": "query", "required": true, "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "findDocumentsByAttributes" } }, "/documents/findByExternalReferenceId": { "get": { "tags": [ "documents" ], "description": "Looks up your orders by their `externalReferenceId` and returns their status. Set `full=true` for the full document objects, or `full=false` (default) for a minimal status (order id, status, externalReferenceId). Scoped to your own orders only – a foreign or unknown reference yields an empty result.", "parameters": [ { "name": "externalReferenceId", "in": "query", "required": true, "type": "string", "maxLength": 64 }, { "name": "full", "in": "query", "required": false, "type": "boolean", "default": false } ], "responses": { "200": { "description": "Matching orders. With `full=false` a list of minimal statuses; with `full=true` a list of full `Document` objects.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentReferenceStatus" } } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "findDocumentsByExternalReferenceId" } }, "/documents/{documentID}": { "get": { "tags": [ "documents" ], "description": "Returns the referenced document. The document is a single letter, a serial letter or an `error` object.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." } }, "operationId": "getDocument" }, "delete": { "tags": [ "documents" ], "description": "Deletes the referenced document. Only possible as long as the document has not yet been handed over for dispatch.\n\nDeletion is only possible while the letter is in a state that permits it. A letter being processed (waiting for validation, being validated, payment or hand-over in progress), in production, printed, or with a cancellation requested is **not** deletable - the answer is then `409` with error code `44091`, and the letter stays untouched. For a serial letter every individual letter must be deletable as well.\n\nDeleting marks the letter as deleted; a letter already handed over to production is **not** recalled by it.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "409": { "description": "Conflict - the document exists but cannot be deleted in its current state. Error code `44091`. A letter is not deletable while it is being processed, while it is in production, printed, or while a cancellation has been requested; for a serial letter every individual letter must be deletable too. Query the status and retry once it has reached a final state." }, "404": { "description": "Document not found - no document exists for the given `documentID`, or it is already marked as deleted. A document belonging to another account yields `403`; one that exists but is not deletable right now yields `409`." } }, "operationId": "deleteDocument" } }, "/documents/{documentID}/status": { "get": { "tags": [ "documents", "status" ], "description": "Returns the status of a single document (`code` and `text`; all codes are listed in the `Status` model).\n\n**Not bound to a phase**, despite what the path suggests: a query for a single id is answered in every state - before the dispatch release, after it, and after delivery. This endpoint, `GET /sendings/{documentID}/status` and `GET /status/{documentID}` therefore return the same thing; for new integrations `GET /status/{documentID}` is the name that says so.\n\n`404` occurs only if the document does not exist, belongs to another account, or has been deleted - by `DELETE /documents/{documentID}` or by the retention period.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "getDocumentStatus" } }, "/documents/{documentID}/options": { "get": { "tags": [ "documents" ], "description": "Returns the document's dispatch options (e.g. simplex/duplex, colour, franking, product, production country).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." } }, "operationId": "getDocumentOptions" }, "put": { "tags": [ "documents" ], "description": "Updates the document's dispatch options. Only possible while the document has not yet been handed over for dispatch.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "options", "in": "body", "schema": { "$ref": "#/definitions/Options" } } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "409": { "description": "Conflict – the state of the document does not permit new shipping options. They can only be changed for drafts and for shippable or erroneous letters; while a letter is being processed, in production or after it was sent, the answer is `409` with error code `44099` (until 7.5 this was `400` with `4400`). A multi-letter document without a single individual letter (splitting it produced none) answers `409` with `44098` – there is nothing its options could apply to; delete it and upload the document again." } }, "operationId": "updateDocumentOptions" } }, "/documents/{documentID}/attributes": { "get": { "tags": [ "documents" ], "description": "Returns the document's attributes (custom `key`/`value` pairs).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "listDocumentAttributes" }, "post": { "tags": [ "documents" ], "description": "Tags the document with attributes (custom `key`/`value` pairs). They can be used later to locate the document via `GET /documents/findbyAttributes`.\n\nAttributes can generally be set or changed at any time. For tenant/reference data please use the dedicated fields `tenantId` and `externalReferenceId` instead of custom attributes.", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" }, { "name": "attributes", "in": "body", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again." } }, "operationId": "addDocumentAttributes" } }, "/documents/{documentID}/attributes/{key}": { "get": { "tags": [ "documents" ], "description": "Returns the document's attribute for the specified `key`.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "key", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "getDocumentAttribute" }, "put": { "tags": [ "documents" ], "description": "Sets the `value` of the attribute for the specified `key`: creates the attribute if the document does not have it yet (**201**), otherwise updates it (**200**). For a serial letter the value is passed on to its individual letters.\n\n`value` is expected as form field (`Content-Type: application/x-www-form-urlencoded`, body `value=…`). It is also accepted as query parameter `?value=…`: a request without body is treated as form whatever its `Content-Type` says – many clients send one by default – and the header may also be omitted. A body in any other format (e.g. JSON) is rejected with **415**.\n\nControl characters and invisible formatting characters are removed from keys and values; tabs, line breaks and special spaces become a single space (at the start or end: nothing). Such values are accepted cleaned, not rejected - reading them back returns the cleaned value.", "consumes": [ "application/x-www-form-urlencoded" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "key", "in": "path", "required": true, "type": "string" }, { "name": "value", "in": "formData", "required": true, "type": "string", "description": "The attribute value – as form field or, alternatively, as query parameter." } ], "responses": { "200": { "description": "Updated – the attribute existed and has been changed.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "201": { "description": "Created – the document did not have this attribute yet; it has been created.", "schema": { "$ref": "#/definitions/LetterAttribute" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again." }, "415": { "description": "Unsupported Media Type – the body is not a form: send `value` as form field (`application/x-www-form-urlencoded`) or as query parameter `?value=…`." } }, "operationId": "setDocumentAttribute" }, "delete": { "tags": [ "documents" ], "description": "Removes the attribute with the specified `key` from the document.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "key", "in": "path", "required": true, "type": "string" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "deleteDocumentAttribute" } }, "/documents/{documentID}/pdf": { "get": { "tags": [ "documents" ], "description": "Returns a PDF preview of the referenced document. Recommended for a visual check after upload or transformation.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "file" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getDocumentPdf" } }, "/documents/{documentID}/png": { "get": { "tags": [ "documents" ], "description": "Returns a PNG preview of the referenced document.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "file" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getDocumentPng" } }, "/documents/{documentID}/transformations": { "put": { "tags": [ "documents", "corrections" ], "description": "Applies a transformation to the document.\n\n- Without a `pages` list, only the **first page** is transformed. To transform **all** pages, pass `[-1]` as `pages`.\n- Each transformation is always applied to the **original** version of the document.\n- After a transformation the document is **validated again** – check `status` afterwards.\n\n**Geometry:**\n- `offsetX` / `offsetY` move the document horizontally / vertically in **mm**; the origin is the upper-left corner of the page.\n- `scaleX` / `scaleY` scale independently; factor `1` = 100 %, values `< 1` shrink. Scaling refers to the **centre** of the page.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "transformation", "in": "body", "required": true, "schema": { "type": "object", "properties": { "pages": { "type": "array", "items": { "type": "integer", "format": "int32" }, "example": [ -1 ], "default": [ 1 ] }, "scaleX": { "type": "number", "format": "double" }, "scaleY": { "type": "number", "format": "double" }, "offsetX": { "type": "number", "format": "double" }, "offsetY": { "type": "number", "format": "double" } } } } ], "responses": { "200": { "description": "Document updated.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again." } }, "operationId": "applyDocumentTransformation" }, "delete": { "tags": [ "documents", "corrections" ], "description": "Removes the applied transformation and rolls the document back to its original version.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again." } }, "operationId": "resetDocumentTransformation" } }, "/documents/{documentID}/coverpage": { "put": { "tags": [ "documents", "corrections" ], "description": "Creates a cover page for the document. The recipient address is **mandatory**; the return address and the text shown below the address are optional.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "coverPage", "in": "body", "schema": { "type": "object", "required": [ "receivingAddress" ], "properties": { "receivingAddress": { "$ref": "#/definitions/Address" }, "returnAddress": { "$ref": "#/definitions/Address" }, "coverText": { "description": "Optional text block on the cover page (subject, date and body text).", "type": "object", "required": [ "text" ], "properties": { "subject": { "description": "Optional subject line on the cover page.", "type": "string" }, "date": { "description": "Optional date on the cover page.", "type": "string", "format": "date" }, "text": { "description": "Body text on the cover page. Plain text only; start a new line with a line break (`\\n`).", "type": "string" } } } } } } ], "responses": { "200": { "description": "Document updated.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again." } }, "operationId": "setDocumentCoverPage" }, "delete": { "tags": [ "documents", "corrections" ], "description": "Removes the cover page from the document.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again." } }, "operationId": "deleteDocumentCoverPage" } }, "/documents/{documentID}/attachments": { "get": { "tags": [ "documents", "attachments" ], "description": "Returns all attachments of the document.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "List of the document's attachments.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Attachment" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "listDocumentAttachments" }, "post": { "tags": [ "documents", "attachments" ], "description": "Uploads a new attachment and appends it to the document, after any attachments already appended. Returns the document's full attachment list.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "appendAttachment", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "newSheet": { "description": "If `true`, the attachment starts on the front of a new sheet. If the field is missing, the default chosen in the customer portal under **Mein Konto → Einstellungen** applies, otherwise `true`. With double-sided printing and an odd number of pages before the attachment, a blank page is inserted for this; it counts towards the number of pages and is charged.", "type": "boolean" }, "remarks": { "description": "Free-text remarks for the attachment.", "type": "string" } } } } ], "responses": { "200": { "description": "Attachment created and appended to the document.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Attachment" } } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again. Nothing was attached." } }, "operationId": "uploadDocumentAttachment" }, "patch": { "tags": [ "documents", "attachments" ], "description": "Appends a list of already-uploaded attachments (by their IDs) to the document. Attachments already appended stay unchanged; the new ones are appended at the end in list order. Mind the order if it matters.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "attachmentIDs", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } ], "responses": { "200": { "description": "Attachments appended; the document's attachment list is returned.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again. Nothing was attached." } }, "operationId": "appendDocumentAttachments" }, "delete": { "tags": [ "documents", "attachments" ], "description": "Detaches all attachments from the document. Only possible before dispatch release.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again." } }, "operationId": "deleteDocumentAttachments" } }, "/documents/{documentID}/attachments/{attachmentID}": { "post": { "tags": [ "documents", "attachments" ], "description": "Appends an already-uploaded attachment, identified by `attachmentID`, to the document – after any attachments already appended. Returns the document.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again. Nothing was attached." } }, "operationId": "appendDocumentAttachment" }, "delete": { "tags": [ "documents", "attachments" ], "description": "Removes the attachment from the document.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Attachment not found – no attachment exists for the given ID. An attachment of a document belonging to another account yields `403`." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. Query `documents/{documentID}/status` and retry afterwards; if ordering failed, the letter can be edited again. The attachment stays attached." } }, "operationId": "removeDocumentAttachment" } }, "/sendings": { "delete": { "tags": [ "sendings" ], "description": "Deletes several finished sendings in one request – cancelled, sent, delivered or returned ones. The bulk variant of `DELETE /sendings/{documentID}`, whose behaviour is unchanged.\n\nEvery id is attempted **on its own**; one id that cannot be deleted does not stop the others and leaves its letter untouched at that moment. The answer is always `200` with one entry per **distinct** requested id, in request order – duplicate ids are collapsed, so **match entries by `id`, never by position**. `deleted` says whether it was deleted, `error` names the reason if it was not: the same error codes the single-document variant returns (`4404` unknown or already deleted, `4403` other account, `44091` state does not permit deletion, `4500` hard error), plus `44092`, which only this bulk variant returns, for a serial letter blocked by its individual letters. **Check every entry; the HTTP status says nothing about the individual results.**\n\nDeleting a serial letter deletes its individual letters as well; `deletedChildren` gives their number without listing them. If an individual letter is requested together with its serial letter, the serial letter is handled first and the individual letter reports `deleted: true` with `deletedAsChildOf` – not `4404`. It also works the other way round: deleting the **last** remaining individual letter of a serial letter deletes the serial letter with it, even when the serial letter itself was not requested – it then has no entry of its own in the answer. The operation is **not atomic**: a partial result is real and is not rolled back.\n\nPass the ids as repeated parameters (`?documentIds=17&documentIds=18`); a comma-separated value is **not** accepted. At most `maxDelete` ids per request (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits), default 250) – above that `413` with error code `44008`, and nothing is deleted.", "produces": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "query", "required": true, "type": "array", "collectionFormat": "multi", "items": { "type": "integer", "format": "int32" }, "description": "The document ids to delete, as repeated parameters." } ], "responses": { "200": { "description": "Successful response – one entry per requested id. Individual ids may still have been rejected; check `deleted` and `error` per entry.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentDeletionStatus" } } }, "400": { "description": "Bad Request – `documentIds` is missing, empty, or carries an empty value (`?documentIds=`). Error code `4400`. Nothing was deleted." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Request Entity Too Large – more ids than `maxDelete` from `GET /accounts/limits` allows (default 250). Error code `44008`. Nothing was deleted; split the list into blocks." } }, "operationId": "deleteSendings" }, "post": { "tags": [ "sendings" ], "description": "Releases one or more already-uploaded, valid documents for dispatch – the **dispatch release**. Pass the `documentIds` of documents that are `ready to ship` (status code 2). Documents are handed to production by default at **14:30**.\n\nFrom this point on a document is managed via `/sendings` (status, cancellation), no longer via `/documents`.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "Idempotency-Key", "in": "header", "type": "string", "required": false, "minLength": 1, "maxLength": 128, "description": "Optional key chosen by the client (e.g. a UUID) that makes this request safe to retry. Scope: this account, this operation, for at least 7 days. Same key and same payload: the stored response of the first request is replayed with `Idempotent-Replayed: true`; nothing is paid or sent twice. Same key with a different payload: `422`, error code `44011`. Same key while the first request is still running: `409`, error code `44010`. Only successful responses are stored; after an error the key may be reused. 1–128 printable ASCII characters, otherwise `400`." } ], "responses": { "409": { "description": "Conflict – a request with this `Idempotency-Key` is still being processed. Error code `44010`. Retry after the first request has finished." }, "422": { "description": "Unprocessable Content – this `Idempotency-Key` was already used with a different payload. Error code `44011`. Use a new key for a new request." }, "200": { "headers": { "Idempotent-Replayed": { "type": "boolean", "description": "`true` when this is the stored response of the first request with the same `Idempotency-Key`; nothing was processed again. Absent on the first execution and without `Idempotency-Key`." } }, "description": "Dispatch accepted – the response lists the documents and their status (a document may be faulty, code 7).", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)." }, "413": { "description": "Request Entity Too Large – more document ids than `maxSendings` from `GET /accounts/limits` allows (default 500). Error code `44009`. Nothing was paid, sent or cancelled; split the list into blocks." } }, "operationId": "releaseForDispatch" }, "get": { "tags": [ "sendings" ], "description": "Returns documents **from the dispatch release onwards**, each with its full details - the status query plus everything else known about the sending.\n\nStatus codes (`status.code` -> `status.text`):\n- **1** - `being created` (de `wird erstellt`) - the release is still being processed (payment, hand-over to production)\n- **3** - `processing` (de `in Verarbeitung`)\n- **4** - `printing` (de `im Druck`)\n- **5** - `sent` (de `versendet`)\n- **6** - `cancelled` (de `storniert`)\n- **7** - `faulty` (de `fehlerhaft`)\n- **8** - `delivered` (de `zugestellt`) - registered mail only, final state\n- **9** - `returned to sender` (de `zurueckgelaufen`) - registered mail only, final state\n\nOnly the uploaded letters themselves are returned; the individual letters of a serial letter are not part of this list. Use `GET /sendings/status` or `GET /status` if you need them.\n\n**Timing:** after the dispatch release the status is only meaningful from **05:00 on the following day**, and only if the sending made the **14:30 dispatch window** - it is not updated before that.\n\nBecause every entry carries the full document, the response grows quickly. Without `limit` the amount is capped at `maxRead` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) (default 500); beyond it the answer is `413` with error code `44007`. For plain status polling use `GET /sendings/status` or `GET /status`.", "parameters": [ { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Content Too Large - more readable documents than `maxRead` from `GET /accounts/limits` allows (default 500), or `limit` above it. Error code `44007`. Use `limit` and `offset`." } }, "operationId": "listSendings" }, "put": { "tags": [ "sendings" ], "description": "Cancels the dispatch of the listed documents (by `documentIds`). Only documents that have **not yet been shipped** can be cancelled; cancellation is possible until **shortly before the 14:30 dispatch window**.", "consumes": [ "application/json" ], "parameters": [ { "name": "documentIds", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } ], "responses": { "200": { "description": "List of document statuses (`documentID` and `status`). For a serial document, the statuses of the child documents are also listed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)." }, "413": { "description": "Request Entity Too Large – more document ids than `maxSendings` from `GET /accounts/limits` allows (default 500). Error code `44009`. Nothing was paid, sent or cancelled; split the list into blocks." } }, "operationId": "cancelDispatch" } }, "/sendings/document": { "post": { "tags": [ "sendings" ], "description": "Uploads a document and, if it validates successfully, sends it **directly** – combining [`POST /documents`](#op:documents:uploadDocument:post:/documents) and [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings) in a single call. The same file rules as for the upload apply (PDF/PS, PDF/A-2b, max **20 MB**, Base64).\n\n**Reliability:** On HTTP `500` the document may still have been created. Send a unique `externalReferenceId` and verify via `GET /documents/findByExternalReferenceId` before retrying (a hit means: it arrived) - or send an `Idempotency-Key`, then a retry with the same key does not dispatch twice.", "consumes": [ "application/json" ], "parameters": [ { "name": "shipping", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "options": { "$ref": "#/definitions/Options" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } }, "tenantId": { "type": "string", "maxLength": 32, "example": "kostenstelle-4711", "description": "Your internal customer/tenant number for this order (max. 32 characters). It is stored on the order and forwarded to production. Replaces the former `tenant` custom attribute. Control characters (e.g. tab, line break), invisible formatting characters and special spaces (e.g. non-breaking space) are rejected with HTTP 400; the error names the position and the character. Legacy custom attributes containing such characters are not mapped." }, "externalReferenceId": { "type": "string", "maxLength": 64, "example": "3f2504e0-4f89-41d3-9a0c-0305e82c3301", "description": "Your internal reference id for this order (max. 64 characters); a **UUID** is the ideal format. Searchable via `GET /documents/findByExternalReferenceId`. Replaces the former `documentID` custom attribute. Control characters (e.g. tab, line break), invisible formatting characters and special spaces (e.g. non-breaking space) are rejected with HTTP 400; the error names the position and the character. Legacy custom attributes containing such characters are not mapped." }, "externalReferenceIdUnique": { "type": "boolean", "default": false, "description": "Opt-in duplicate protection. If `true`, the request is rejected when another of your orders already carries this `externalReferenceId` (guards against accidental double submissions)." }, "responseFormat": { "$ref": "#/definitions/ResponseFormatEnum" } }, "example": { "content": { "filename": "musterbrief.pdf", "content": "" }, "tenantId": "kostenstelle-4711", "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } } }, { "name": "Idempotency-Key", "in": "header", "type": "string", "required": false, "minLength": 1, "maxLength": 128, "description": "Optional key chosen by the client (e.g. a UUID) that makes this request safe to retry. Scope: this account, this operation, for at least 7 days. Same key and same payload: the stored response of the first request is replayed with `Idempotent-Replayed: true`; nothing is paid or sent twice. Same key with a different payload: `422`, error code `44011`. Same key while the first request is still running: `409`, error code `44010`. Only successful responses are stored; after an error the key may be reused. 1–128 printable ASCII characters, otherwise `400`." } ], "responses": { "409": { "description": "Conflict – a request with this `Idempotency-Key` is still being processed. Error code `44010`. Retry after the first request has finished. Also: the document exists but can't be sent in its current state (erroneous, still being validated, being ordered, already paid or sent; for a serial letter, every individual letter must be shippable) - error code `44093`. Query `documents/{documentID}/status` and retry once it is shippable." }, "422": { "description": "Unprocessable Content – this `Idempotency-Key` was already used with a different payload. Error code `44011`. Use a new key for a new request." }, "200": { "headers": { "Idempotent-Replayed": { "type": "boolean", "description": "`true` when this is the stored response of the first request with the same `Idempotency-Key`; nothing was processed again. Absent on the first execution and without `Idempotency-Key`." } }, "description": "Document created and dispatched – may be faulty (check `status`; code 7 = faulty).", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." }, "413": { "description": "Request Entity Too Large – the file exceeds the maximum upload size (20 MB, see `maxUploadSize` in `GET /accounts/limits`)." } }, "operationId": "uploadAndSendDocument" } }, "/sendings/status": { "get": { "tags": [ "sendings", "status" ], "description": "Returns the status of documents **from the dispatch release onwards** - `documentID` plus `status` (`code` and `text`), no document details.\n\nStatus codes in this phase:\n- **1** - `being created` (de `wird erstellt`) - the release is still being processed (payment, hand-over to production)\n- **3** `processing`, **4** `printing`, **5** `sent`, **6** `cancelled`, **7** `faulty`, **8** `delivered` (registered mail only), **9** `returned to sender` (registered mail only)\n\n`documentIds` changes the behaviour:\n- **with** `documentIds`: exactly the requested documents, in **any** state - an id-based query is not bound to the phase. Ids that cannot be read are omitted; `404` only if none of them can be read.\n- **without** `documentIds`: all sendings of the account, including the individual letters of a serial letter.\n\nUse `limit` and `offset` to page. Without `limit` the amount is capped at `maxReadStatus` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) (default 5000); beyond it the answer is `413` with error code `44007`.\n\n**From when it delivers:** without `documentIds` a letter appears here only at the dispatch release - `GET /documents/status` answers it before that. `GET /status` spans both phases and does not have this break.\n\n**Timing:** progress is only meaningful from **05:00 on the following day**, and only if the sending made the **14:30 dispatch window**.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "413": { "description": "Content Too Large - more readable documents than `maxReadStatus` from `GET /accounts/limits` allows (default 5000), or `limit` above it. Error code `44007`. Use `limit` and `offset`." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Sending not found - none of the ids given in `documentIds` can be read for this account. Without `documentIds` this code does not occur; an account with no sendings receives an empty list with 200." } }, "operationId": "listSendingStatus" } }, "/sendings/{documentID}/status": { "get": { "tags": [ "sendings", "status" ], "description": "Returns the status of a single document (`code` and `text`; all codes are listed in the `Status` model).\n\n**Not bound to a phase**, despite what the path suggests: a query for a single id is answered in every state - before the dispatch release, after it, and after delivery. This endpoint, `GET /sendings/{documentID}/status` and `GET /status/{documentID}` therefore return the same thing; for new integrations `GET /status/{documentID}` is the name that says so.\n\n`404` occurs only if the document does not exist, belongs to another account, or has been deleted - by `DELETE /documents/{documentID}` or by the retention period.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "getSendingStatus" } }, "/sendings/{documentID}": { "post": { "tags": [ "sendings" ], "description": "Releases a single document for dispatch, if it has not yet been shipped (single-document variant of [`POST /sendings`](#op:sendings:releaseForDispatch:post:/sendings)).", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" }, { "name": "Idempotency-Key", "in": "header", "type": "string", "required": false, "minLength": 1, "maxLength": 128, "description": "Optional key chosen by the client (e.g. a UUID) that makes this request safe to retry. Scope: this account, this operation, for at least 7 days. Same key and same payload: the stored response of the first request is replayed with `Idempotent-Replayed: true`; nothing is paid or sent twice. Same key with a different payload: `422`, error code `44011`. Same key while the first request is still running: `409`, error code `44010`. Only successful responses are stored; after an error the key may be reused. 1–128 printable ASCII characters, otherwise `400`." } ], "responses": { "409": { "description": "Conflict – a request with this `Idempotency-Key` is still being processed. Error code `44010`. Retry after the first request has finished. Also: the document exists but can't be sent in its current state (erroneous, still being validated, being ordered, already paid or sent; for a serial letter, every individual letter must be shippable) - error code `44093`. Query `documents/{documentID}/status` and retry once it is shippable." }, "422": { "description": "Unprocessable Content – this `Idempotency-Key` was already used with a different payload. Error code `44011`. Use a new key for a new request." }, "200": { "headers": { "Idempotent-Replayed": { "type": "boolean", "description": "`true` when this is the stored response of the first request with the same `Idempotency-Key`; nothing was processed again. Absent on the first execution and without `Idempotency-Key`." } }, "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Document" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "releaseDocumentForDispatch" }, "get": { "tags": [ "sendings" ], "description": "Returns a referenced sending. The sending is a single letter, a serial letter or an `error` object.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Document" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." } }, "operationId": "getSending" }, "put": { "tags": [ "sendings" ], "description": "Cancels the dispatch of a single document, if it has not yet been shipped (single-document variant of the cancellation).", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Status" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID`. A document belonging to another account yields `403`." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." }, "409": { "description": "Conflict – the document is being ordered right now (released for payment and dispatch) and can't be cancelled yet. Error code `44090`. Query `sendings/{documentID}/status` and retry once ordering has finished; whether the letter can be cancelled then depends on its new state (otherwise `406`)." } }, "operationId": "cancelDocumentDispatch" }, "delete": { "tags": [ "sendings" ], "description": "Deletes a finished document from the system - i.e. one that is cancelled, or delivered and sent. Use this to remove completed entries.\n\nDeletion is only possible while the letter is in a state that permits it. A letter being processed (waiting for validation, being validated, payment or hand-over in progress), in production, printed, or with a cancellation requested is **not** deletable - the answer is then `409` with error code `44091`, and the letter stays untouched. For a serial letter every individual letter must be deletable as well.\n\nDeleting marks the letter as deleted; a letter already handed over to production is **not** recalled by it.", "parameters": [ { "in": "path", "name": "documentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "409": { "description": "Conflict - the document exists but cannot be deleted in its current state. Error code `44091`. A letter is not deletable while it is being processed, while it is in production, printed, or while a cancellation has been requested; for a serial letter every individual letter must be deletable too. Query the status and retry once it has reached a final state." }, "404": { "description": "Document not found - no document exists for the given `documentID`, or it is already marked as deleted. A document belonging to another account yields `403`; one that exists but is not deletable right now yields `409`." } }, "operationId": "deleteSending" } }, "/regmails/": { "get": { "tags": [ "regmails", "sendings", "status" ], "description": "Returns status and tracking information for registered mail (Einschreiben) - per entry the `documentID`, `product`, `status` (`code` and `text`) and, once available, `tracking` with the consignment number and a tracking address.\n\nTracking information appears only once the item is in delivery; before that `tracking` is absent. From then on it can be followed all the way to the mailbox, and the status reaches **8** `delivered` or **9** `returned to sender` - both final states that exist only for registered mail.\n\n`documentIds` changes the behaviour:\n- **with** `documentIds`: exactly the requested items. If any of the ids does not belong to this account the request is rejected **as a whole** with `403` - unlike `GET /status`, which omits unreadable ids individually.\n- **without** `documentIds`: all registered mail of the account.\n\nUse `limit` and `offset` to page. Without `limit` the amount is capped at `maxReadStatus` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) (default 5000); beyond it the answer is `413` with error code `44007`.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/RegmailStatus" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Content Too Large - more registered-mail items than `maxReadStatus` from `GET /accounts/limits` allows (default 5000), or `limit` above it. Error code `44007`. Use `limit` and `offset`." }, "404": { "description": "Not found - none of the requested orders is a registered-mail item. They all belong to this account; a foreign or unknown id yields `403` instead. Without `documentIds` this code does not occur: an account without registered mail receives an empty list with 200." } }, "operationId": "listRegisteredMail" } }, "/regmails/{documentID}": { "get": { "tags": [ "regmails", "sendings", "status" ], "description": "Returns status and tracking information for a SINGLE registered-mail item (`product`, `status`, and `tracking` once available).\n\nTracking information appears only once the item is in delivery and can then be followed all the way to the mailbox; the final states **8** `delivered` and **9** `returned to sender` exist only for registered mail.\n\nThe response is a single object with a fixed shape - it contains no list that could grow. This endpoint therefore deliberately has NO `limit`/`offset`: such a parameter would have no effect. To page over several items use `GET /regmails` with `documentIds`, `limit` and `offset`.\n\n`403` covers both: the order belongs to another account OR it does not exist. The two cases are deliberately not distinguished, so the answer does not reveal whether a foreign id exists.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/RegmailStatus" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Not found - the order belongs to this account but is not a registered-mail item, so there is no tracking data for it. A foreign or unknown `documentID` yields `403`, not `404`." } }, "operationId": "getRegisteredMail" } }, "/status": { "get": { "tags": [ "status" ], "description": "Returns the status of documents in **every** phase of their lifecycle - before dispatch release, after it, and after delivery. Unlike `GET /documents/status` and `GET /sendings/status` this endpoint is not bound to a phase: the same `documentID` keeps being answered from upload to the final state, so one poll loop is enough.\n\nOnly the status is returned - `documentID` plus `status` (`code` and `text`); **no document details**. Use `GET /documents/{documentID}` (before dispatch release) or `GET /sendings/{documentID}` (after it) for those.\n\n`documentIds` changes the behaviour:\n- **with** `documentIds`: exactly the requested documents, in any state. Ids that do not exist, belong to another account or are deleted are omitted; `404` only if none of them can be read.\n- **without** `documentIds`: all documents of the account, including the individual letters of a serial letter (they can be dispatched individually through this API). Drafts and letters still being written in the web interface are never returned.\n\nUse `limit` and `offset` to page. Without `limit` the number of readable documents is capped at `maxReadStatus` from [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits) (default 5000); beyond it the answer is `413` with error code `44007`.\n\nNothing is returned once a document has been deleted - by `DELETE /documents/{documentID}` or by the retention period.", "parameters": [ { "name": "documentIds", "in": "query", "required": false, "type": "array", "items": { "type": "integer", "format": "int32" }, "collectionFormat": "multi" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response - the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "413": { "description": "Content Too Large - more readable documents than `maxReadStatus` from `GET /accounts/limits` allows (default 5000), or `limit` above it. Error code `44007`. Use `limit` and `offset`." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found - none of the ids given in `documentIds` can be read for this account. Without `documentIds` this code does not occur; an account without documents receives an empty list with 200." } }, "operationId": "listLifecycleStatus" } }, "/status/{documentID}": { "get": { "tags": [ "status" ], "description": "Returns the status of a **single** document in every phase of its lifecycle (`code` and `text`). The `documentID` stays valid across the whole lifecycle: unlike the phase-bound endpoints this one keeps answering after the dispatch release and after delivery. Individual letters of a serial letter are answered as well.\n\nOnly the status is returned - **no document details**; use `GET /documents/{documentID}` or `GET /sendings/{documentID}` for those.\n\n`404` occurs only if the document does not exist, belongs to another account, or has been deleted - by `DELETE /documents/{documentID}` or by the retention period.", "parameters": [ { "name": "documentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response - the request was processed.", "schema": { "$ref": "#/definitions/DocumentStatus" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found - the document does not exist, belongs to another account, or has been deleted." } }, "operationId": "getLifecycleStatus" } }, "/attachments": { "post": { "tags": [ "attachments" ], "description": "Uploads a new attachment to the attachment pool. The attachment can then be appended to documents (e.g. via `POST /documents/{documentID}/attachments/{attachmentID}`).", "consumes": [ "application/json" ], "parameters": [ { "name": "attachmentData", "in": "body", "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "$ref": "#/definitions/Content" }, "newSheet": { "description": "If `true`, the attachment starts on the front of a new sheet. If the field is missing, the default chosen in the customer portal under **Mein Konto → Einstellungen** applies, otherwise `true`. With double-sided printing and an odd number of pages before the attachment, a blank page is inserted for this; it counts towards the number of pages and is charged.", "type": "boolean" }, "remarks": { "description": "Free-text remarks for the attachment.", "type": "string" } } } } ], "responses": { "200": { "description": "Attachment created in the pool.", "schema": { "$ref": "#/definitions/Attachment" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Request Entity Too Large – the file exceeds the maximum upload size (20 MB, see `maxUploadSize` in `GET /accounts/limits`)." } }, "operationId": "uploadAttachment" }, "get": { "tags": [ "attachments" ], "description": "Returns all attachments in the pool.", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Attachment" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "listAttachments" } }, "/attachments/{attachmentID}": { "get": { "tags": [ "attachments" ], "description": "Returns the referenced attachment.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Attachment" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)." } }, "operationId": "getAttachment" }, "delete": { "tags": [ "attachments" ], "description": "Deletes the referenced attachment. Only possible if it is not currently appended to any not-yet-shipped document – detach it first via `DELETE /attachments/{attachmentID}/documents`.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "deleteAttachment" } }, "/attachments/{attachmentID}/pdf": { "get": { "tags": [ "attachments" ], "description": "Returns a PDF preview of the referenced attachment.", "parameters": [ { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "file" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getAttachmentPdf" } }, "/attachments/{attachmentID}/png": { "get": { "tags": [ "attachments" ], "description": "Returns a PNG preview of the referenced attachment's first page.", "parameters": [ { "name": "attachmentID", "in": "path", "required": true, "type": "integer", "format": "int32" } ], "produces": [ "*/*" ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "file" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)." }, "406": { "description": "Not Acceptable – the requested representation cannot be provided (e.g. no preview available for this document)." } }, "operationId": "getAttachmentPng" } }, "/attachments/{attachmentID}/documents": { "get": { "tags": [ "attachments" ], "description": "Returns all not-yet-shipped documents this attachment is appended to.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Document" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)." } }, "operationId": "listAttachmentDocuments" }, "patch": { "tags": [ "attachments" ], "description": "Appends this attachment to all documents in the list. It is appended at the end of each document, after any attachments already present.", "consumes": [ "application/json" ], "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" }, { "name": "doumentIDs", "in": "body", "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } } ], "responses": { "200": { "description": "Attachment appended to all documents in the list.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document(s) do not exist – one or more of the given IDs were not found (or are not accessible for this account)." }, "409": { "description": "Conflict – at least one of the documents is being ordered right now (released for payment and dispatch) and is locked until ordering has finished. Error code `44090`. The attachment was not attached to any of the documents. Query their status and retry afterwards." } }, "operationId": "attachToDocuments" }, "delete": { "tags": [ "attachments" ], "description": "Removes the referenced attachment from all documents that have not yet been shipped.", "parameters": [ { "in": "path", "name": "attachmentID", "required": true, "type": "integer", "format": "int32" } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/DocumentStatus" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Attachment not found – no attachment exists for the given ID (or it is not accessible for this account)." } }, "operationId": "detachFromDocuments" } }, "/accounts": { "get": { "tags": [ "accounts" ], "description": "Returns the account's financial data (e.g. balance).", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Account" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "getAccount" } }, "/accounts/limits": { "get": { "tags": [ "accounts" ], "description": "Returns the effective bounds of this environment (production or test): the maximum `limit` per page, the maximum number of ids per bulk request and the maximum upload size. Read them once at start-up instead of hard-coding defaults; every `413` of this API refers to one of these values.", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Limits" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "getAccountLimits" } }, "/accounts/personaldata": { "get": { "tags": [ "accounts" ], "description": "Returns the account's personal data.", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/User" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "User not found – no user exists for the given account or identifier." } }, "operationId": "getPersonalData" }, "patch": { "tags": [ "accounts" ], "description": "Updates the account's personal data.", "parameters": [ { "name": "personalData", "in": "body", "required": true, "schema": { "description": "The customer's personal data.", "type": "object", "properties": { "forename": { "type": "string" }, "surname": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "plz": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" }, "title": { "type": "string" }, "phone": { "type": "string" }, "partnerId": { "type": "string" } } } } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/User" } }, "400": { "description": "Bad Request – the request is malformed (e.g. missing required fields or invalid values)." }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "User not found – no user exists for the given account or identifier." } }, "operationId": "updatePersonalData" } }, "/accounts/options": { "get": { "tags": [ "accounts" ], "description": "Returns the default dispatch options assigned to the account (applied to new documents).", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "User not found – no user exists for the given account or identifier." } }, "operationId": "getAccountOptions" }, "put": { "tags": [ "accounts" ], "description": "Updates the default dispatch options assigned to the account.", "parameters": [ { "name": "defaultOptions", "in": "body", "required": true, "schema": { "$ref": "#/definitions/Options" } } ], "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "$ref": "#/definitions/Options" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "User not found – no user exists for the given account or identifier." } }, "operationId": "updateAccountOptions" } }, "/accounts/coworkers": { "get": { "tags": [ "accounts" ], "description": "Returns the account's coworkers (sub-users).", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Coworker" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "listCoworkers" } }, "/accounts/coworkers/{debitornumber}/journal/{month}": { "get": { "tags": [ "accounts" ], "description": "Returns all transactions of the given month for a specific coworker (identified by `debitornumber`).", "parameters": [ { "in": "path", "name": "debitornumber", "required": true, "type": "string" }, { "in": "path", "name": "month", "required": true, "type": "integer", "format": "int32" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" }, { "name": "order", "in": "query", "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "description": "Sort order by transaction id: `asc` (oldest first; default) or `desc` (newest first). With `desc`, `offset=0` is the most recent page. Any other value: `400`." } ], "responses": { "400": { "description": "Bad Request – `order` is neither `asc` nor `desc`, or `limit`/`offset` are invalid. Error code `4400`." }, "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "User not found – no user exists for the given account or identifier." }, "413": { "description": "Content Too Large – more rows than `maxRead` from `GET /accounts/limits` allows (default 500), or `limit` above it. Error code `44007`. Use `limit` (at most `maxRead`) and `offset`." } }, "operationId": "getCoworkerJournal" } }, "/accounts/journal/{month}": { "get": { "tags": [ "accounts" ], "description": "Returns all transactions of the given month for the account.", "parameters": [ { "in": "path", "name": "month", "required": true, "type": "integer", "format": "int32" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" }, { "name": "order", "in": "query", "type": "string", "enum": [ "asc", "desc" ], "default": "asc", "description": "Sort order by transaction id: `asc` (oldest first; default) or `desc` (newest first). With `desc`, `offset=0` is the most recent page. Any other value: `400`." } ], "responses": { "400": { "description": "Bad Request – `order` is neither `asc` nor `desc`, or `limit`/`offset` are invalid. Error code `4400`." }, "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Content Too Large – more rows than `maxRead` from `GET /accounts/limits` allows (default 500), or `limit` above it. Error code `44007`. Use `limit` (at most `maxRead`) and `offset`." } }, "operationId": "getAccountJournal" } }, "/accounts/authentication": { "get": { "tags": [ "accounts" ], "description": "Shows how this request was signed in: the method (`PASSWORD` or `API_KEY`), the transport (`BASIC`, `BEARER`, `X_API_KEY`, `BASIC_BRIDGE` or `RAW`), the sign-in mode of this login (`authMode`) and the client IP address the server sees – the address an IP allow list (`allowedIps`) is checked against. Signed in with an API key, `apiKey` describes that key (masked). Useful for testing a new key or the set-up of a client.", "responses": { "200": { "description": "Successful response – the sign-in of this request.", "schema": { "$ref": "#/definitions/Authentication" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "getAuthentication" } }, "/invoices": { "get": { "tags": [ "invoices" ], "description": "Returns references to all stored invoices.", "responses": { "200": { "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Invoice" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." } }, "operationId": "listInvoices" } }, "/invoices/{invoiceNumber}": { "get": { "tags": [ "invoices" ], "description": "Returns all transactions of the invoice.", "parameters": [ { "in": "path", "name": "invoiceNumber", "required": true, "type": "string" }, { "name": "limit", "in": "query", "type": "integer", "format": "int32", "collectionFormat": "multi" }, { "name": "offset", "in": "query", "type": "integer", "format": "int32" } ], "responses": { "200": { "headers": { "X-Page-Limit": { "type": "integer", "description": "Effective page size of this response: the `limit` sent, otherwise the configured bound (see [`GET /accounts/limits`](#op:accounts:getAccountLimits:get:/accounts/limits)). Absent when the response was not paged: status queries with explicit `documentIds` return all requested ids at once." }, "X-Page-Offset": { "type": "integer", "description": "Offset of this page (`0` when none was sent)." }, "X-Next-Offset": { "type": "integer", "description": "Offset of the next page. Present only when this page was full (as many rows as `X-Page-Limit`), i.e. more rows may follow. Absent means: last page." }, "Link": { "type": "string", "description": "Web links (RFC 8288) to the neighbouring pages: `rel=\"next\"` only when this page was full, `rel=\"prev\"` only when `offset` was above `0`. Paths start below the API base path and keep all filters of this request." } }, "description": "Successful response – the request was processed.", "schema": { "type": "array", "items": { "$ref": "#/definitions/Transaction" } } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "413": { "description": "Content Too Large – more rows than `maxRead` from `GET /accounts/limits` allows (default 500), or `limit` above it. Error code `44007`. Use `limit` (at most `maxRead`) and `offset`." } }, "operationId": "getInvoiceTransactions" } }, "/invoices/{invoiceNumber}/pdf": { "get": { "tags": [ "invoices" ], "description": "Returns the invoice as a PDF.", "parameters": [ { "in": "path", "name": "invoiceNumber", "required": true, "type": "string" } ], "responses": { "200": { "description": "The invoice as a PDF.", "schema": { "type": "file" } }, "401": { "description": "Unauthorized – no or malformed credentials (e.g. no `Authorization` header and no API key in `X-API-Key`, unknown scheme, invalid Base64; error code `4401`), or an invalid, deactivated or expired API key (error codes `44012`, `44013`, `44014`). The `WWW-Authenticate` header names the expected scheme: `Bearer realm=\"binectapi\"`, for a rejected key with `error=\"invalid_token\"`." }, "403": { "description": "Forbidden – wrong e-mail address or password, the login is locked, or no permission for this resource (error code `4403`). With a password also: sign-in with password is disabled for this login, it only accepts API keys (`44034`). With an API key also: API keys are not enabled for this login (`44031`) or your main account has blocked them (`44036`), the key may not be used from this IP address (`44032`), or the key is read-only and the request writes (`44033`, `WWW-Authenticate` with `error=\"insufficient_scope\"`)." }, "404": { "description": "Document not found – no document exists for the given `documentID` (or it is not accessible for this account)." } }, "operationId": "getInvoicePdf" } } }, "definitions": { "DocumentDeletionStatus": { "type": "object", "required": [ "id", "deleted" ], "properties": { "id": { "type": "integer", "format": "int32", "description": "The document id as requested." }, "deleted": { "type": "boolean", "description": "true if this request deleted the document." }, "deletedChildren": { "type": "integer", "format": "int32", "description": "Number of individual letters of this serial letter deleted together with it. Present only for serial letters that **were** deleted – a rejected one carries no `deletedChildren`; their ids are never listed. 0 means the serial letter had no undeleted individual letters left." }, "deletedAsChildOf": { "type": "integer", "format": "int32", "description": "This document is an individual letter of the serial letter with this id, which was deleted earlier in the same request; the letter went with it. Present instead of an error, because the document did exist when the request arrived." }, "error": { "$ref": "#/definitions/Error" } }, "example": { "id": 4711, "deleted": true, "deletedChildren": 3 } }, "Document": { "type": "object", "example": { "id": 4711, "filename": "letter.pdf", "numberOfPages": 1, "documentType": "Letter", "status": { "code": 2, "text": "versandbereit" }, "letter": { "letterType": "LetterData", "letterData": { "recipientAddress": "\"Musterfirma GmbH\" \"Max Mustermann\" \"Musterstraße 1\" \"12345 Musterstadt\"", "international": false, "options": { "simplex": true, "color": false, "envelope": "DINLANG", "franking": "DV_FRANKING", "product": "NORMAL", "productionCountry": "DE" }, "price": { "priceBeforeTax": 89, "priceAfterTax": 106, "unit": "EUROCENT", "taxInPercent": 19 }, "attributes": [ { "key": "documentID", "value": "DOC-2024-0001" } ] } } }, "required": [ "id", "filename", "status", "documentType" ], "properties": { "id": { "type": "integer", "format": "int32" }, "filename": { "type": "string" }, "numberOfPages": { "description": "Number of pages of the letter including its attachments and the blank pages inserted for printing (a blank page before an attachment that starts on a new sheet; with double-sided printing the blank back of a cover page). This is the number of pages that is printed and charged – before and after dispatch.", "type": "integer", "format": "int32" }, "status": { "$ref": "#/definitions/Status" }, "documentType": { "description": "Type of document.\n- `Letter` – single letter\n- `SerialLetter` – serial letter (split into multiple letters)", "type": "string", "enum": [ "Letter", "SerialLetter" ] }, "letter": { "$ref": "#/definitions/Letter" }, "serialLetter": { "$ref": "#/definitions/SerialLetter" } } }, "Attachment": { "type": "object", "required": [ "id", "filename", "numberOfPages", "newSheet" ], "properties": { "id": { "type": "integer", "format": "int32" }, "filename": { "type": "string" }, "numberOfPages": { "type": "integer", "format": "int32" }, "newSheet": { "type": "boolean", "default": true }, "ntimesUsed": { "description": "Number of documents this attachment is currently appended to.", "type": "integer", "format": "int32" }, "remarks": { "type": "string" }, "validation": { "$ref": "#/definitions/ValidationResult" } } }, "ValidationResult": { "type": "object", "description": "Result of the automatic document check: whether the recipient address was read by text recognition (OCR) and which corrections were applied to the document so that it can be printed and delivered. A missing field means that this information is not available for the document, for example because it was checked before the information was recorded – it does not mean `false` or \"no correction\".", "example": { "ocrApplied": false, "corrections": [ "rotate" ], "validatedAt": "2026-10-21T09:14:03.120+02:00", "durationMs": 1834 }, "properties": { "ocrApplied": { "description": "`true` if the recipient address was read from the document by text recognition (OCR). Please check such addresses with particular care.", "type": "boolean" }, "corrections": { "description": "Corrections applied automatically; they are part of the check and cannot be deselected. Values: `white` – restricted area blanked, `rotate` – page rotated (and scaled if necessary), `shrink` – attachment scaled down, `pageformat` – page format corrected. Further values may be added; treat unknown values as \"other correction\". An empty list means that the document was checked and nothing had to be corrected.", "type": "array", "items": { "type": "string" } }, "validatedAt": { "description": "Time of the most recent check.", "type": "string", "format": "date-time" }, "durationMs": { "description": "Duration of the most recent check in milliseconds, including waiting time.", "type": "integer", "format": "int32" } } }, "Letter": { "type": "object", "required": [ "letterType" ], "properties": { "letterType": { "description": "Type of letter content.\n- `LetterData` – valid letter data\n- `Error` – an error object (validation failed)", "type": "string", "enum": [ "LetterData", "Error" ] }, "letterData": { "$ref": "#/definitions/LetterData" }, "errors": { "type": "array", "items": { "$ref": "#/definitions/Error" } } } }, "LetterData": { "type": "object", "required": [ "recipientAddress", "price", "international", "options" ], "properties": { "recipientAddress": { "description": "Recipient address as detected in the letter's address field. Format: each part in quotes, space-separated (company/name, name, street, ZIP + city).", "type": "string", "example": "\"Musterfirma\" \"Max Mustermann\" \"Musterstr. 20\" \"64342 Musterstadt\"" }, "price": { "$ref": "#/definitions/Price" }, "international": { "type": "boolean", "default": false, "example": false }, "options": { "$ref": "#/definitions/Options" }, "tracking": { "$ref": "#/definitions/Tracking" }, "attributes": { "type": "array", "items": { "$ref": "#/definitions/LetterAttribute" } }, "attachments": { "description": "The attachments appended to this document. Only documents of `documentType` `Letter` can have attachments.", "type": "array", "items": { "$ref": "#/definitions/Attachment" } }, "validation": { "$ref": "#/definitions/ValidationResult" } } }, "SerialLetter": { "type": "object", "example": { "splitToken": "###NEXT###", "status": { "nrTotal": 50, "nrGenerated": 50, "nrSuccess": 49, "nrError": 1 } }, "properties": { "splitToken": { "type": "string", "description": "Text token at which the serial letter is split into individual letters." }, "splitAfterNumberOfPages": { "type": "integer", "format": "int32", "description": "The serial letter is split every N pages." }, "status": { "$ref": "#/definitions/SerialLetterStatus" }, "letters": { "type": "array", "items": { "$ref": "#/definitions/Document" } } } }, "SerialLetterStatus": { "type": "object", "required": [ "nrTotal", "nrGenerated", "nrSuccess", "nrError" ], "properties": { "nrTotal": { "type": "integer", "format": "int32" }, "nrGenerated": { "type": "integer", "format": "int32" }, "nrSuccess": { "type": "integer", "format": "int32" }, "nrError": { "type": "integer", "format": "int32" } } }, "Error": { "type": "object", "required": [ "code", "text", "blankText" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "Binect error code. A machine-readable, bilingual list (code → meaning) is published at /binectapi/error-codes.json." }, "text": { "type": "string", "description": "Human-readable error text with placeholders filled in." }, "blankText": { "type": "string", "description": "Error text with placeholders for parameters. Placeholders are framed by %-symbols, e.g. `error on page number %pageNr% of your document`." }, "parameters": { "type": "array", "description": "Values for the placeholders in `blankText`.", "items": { "$ref": "#/definitions/ErrorParam" } }, "errorOnPage": { "type": "integer", "format": "int32", "description": "Page of the document on which the error occurred." } } }, "Price": { "type": "object", "required": [ "priceBeforeTax", "priceAfterTax", "unit", "taxInPercent" ], "properties": { "priceBeforeTax": { "type": "integer", "format": "int32" }, "priceAfterTax": { "type": "integer", "format": "int32" }, "unit": { "$ref": "#/definitions/CurrencyEnum" }, "taxInPercent": { "type": "integer", "format": "int32", "description": "Sales-tax rate in percent, e.g. `19` for 19 % VAT." }, "details": { "type": "array", "description": "Price breakdown by differing sales-tax rates (e.g. 19 % and 0 %).", "items": { "$ref": "#/definitions/Price" } } }, "example": { "priceBeforeTax": 78, "priceAfterTax": 93, "unit": "EUROCENT", "taxInPercent": 19 } }, "Options": { "type": "object", "properties": { "simplex": { "description": "Single-sided print if `true`; double-sided (duplex) if `false`.", "type": "boolean" }, "color": { "description": "Colour print if `true`; black & white if `false`.", "type": "boolean" }, "envelope": { "description": "Envelope format. Default is `DINLANG`.\n- `DINLANG` – DIN long (folded letter)\n- `C4` – C4 (unfolded, A4)", "type": "string", "enum": [ "DINLANG", "C4" ], "example": "DINLANG" }, "dvFranking": { "description": "If `true`, DV-Freimachung is mandatory and validation is stricter. **Deprecated** – use `franking` (`DV_FRANKING`) instead.", "type": "boolean" }, "franking": { "$ref": "#/definitions/FrankingEnum" }, "productionCountry": { "$ref": "#/definitions/ProductionCountryEnum" }, "product": { "$ref": "#/definitions/ProductEnum" }, "shippingDate": { "description": "Optional scheduled dispatch date: the letter is released now but is produced and dispatched no earlier than this day.\nAccepts EITHER a fixed date in `YYYY-MM-DD` or `DD-MM-YYYY` format, OR a weekday: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`. For a weekday the next matching business day is used. Only Monday–Friday are supported. On upload a weekday is frozen to a fixed date; on `/accounts/options` only a weekday is accepted. Send an empty string (\"\") for explicitly no dispatch date (ignores the account default on upload, removes it on /accounts/options); omit the field to inherit/keep the account default. Present in responses only when set.", "type": "string", "example": "2026-08-03" } }, "example": { "simplex": true, "color": false, "envelope": "DINLANG", "franking": "DV_FRANKING", "productionCountry": "DE", "shippingDate": "2026-08-03" } }, "FrankingEnum": { "description": "Franking method.\n- `STANDARD_FRANKING` – standard franking\n- `DV_FRANKING` – DV-Freimachung: modern method for fast dispatch with the maximum feature set (recommended)\n- `UNSPECIFIED` – not specified; the account default applies", "type": "string", "enum": [ "UNSPECIFIED", "STANDARD_FRANKING", "DV_FRANKING" ] }, "ProductionCountryEnum": { "description": "Country from which domestic mail is produced. International mail is always produced in Germany. Use requires prior approval by Binect.\n- `DE` – Germany\n- `AT` – Austria\n- `UNSPECIFIED` – not specified (default)", "type": "string", "enum": [ "UNSPECIFIED", "DE", "AT" ] }, "RegmailStatus": { "type": "object", "required": [ "id", "product", "status" ], "properties": { "id": { "type": "integer", "format": "int32" }, "product": { "$ref": "#/definitions/ProductEnum" }, "status": { "$ref": "#/definitions/Status" }, "tracking": { "$ref": "#/definitions/Tracking" } } }, "Tracking": { "type": "object", "properties": { "trackingId": { "type": "string" }, "trackingUrl": { "type": "string", "format": "uri" } } }, "ProductEnum": { "description": "Postal product. Default is `NORMAL` (standard letter).\n- `NORMAL` – standard letter\n- `PREMIUMADRESS_BASIS` / `PREMIUMADRESS_REPORT` – Deutsche Post PREMIUMADRESS (recipient address-update service); for usage please contact kontakt@binect.de\n- `REGMAIL` – registered mail (Einschreiben)\n- `REGMAIL_DROP` – Einwurf-Einschreiben\n- `REGMAIL_INTERNATIONAL` – international registered mail", "type": "string", "enum": [ "NORMAL", "PREMIUMADRESS_BASIS", "PREMIUMADRESS_REPORT", "REGMAIL", "REGMAIL_DROP", "REGMAIL_INTERNATIONAL" ] }, "LetterAttribute": { "type": "object", "description": "A custom attribute (key/value) of a document. Control characters and invisible formatting characters are removed from keys and values; tabs, line breaks and special spaces become a single space (at the start or end: nothing). Such values are accepted cleaned, not rejected - reading them back returns the cleaned value.", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } }, "example": { "key": "documentID", "value": "DOC-2024-0001" } }, "DocumentStatus": { "type": "object", "required": [ "id", "status" ], "properties": { "id": { "type": "integer", "format": "int32" }, "status": { "$ref": "#/definitions/Status" } } }, "DocumentReferenceStatus": { "type": "object", "required": [ "id", "status", "externalReferenceId" ], "properties": { "id": { "type": "integer", "format": "int32", "description": "The order id." }, "status": { "$ref": "#/definitions/Status" }, "externalReferenceId": { "type": "string", "description": "The external reference id this order was found by." } }, "example": { "id": 4711, "status": { "code": 5, "text": "versendet" }, "externalReferenceId": "3f2504e0-4f89-41d3-9a0c-0305e82c3301" } }, "Status": { "type": "object", "required": [ "code", "text" ], "properties": { "code": { "description": "The following status codes exist. The `text` is returned in the account's language (German or English):\n\n- **1** – `being created` (de `wird erstellt`)\n- **2** – `ready to ship` (de `versandbereit`)\n- **3** – `processing` (de `in Verarbeitung`)\n- **4** – `printing` (de `im Druck`)\n- **5** – `sent` (de `versendet`)\n- **6** – `cancelled` (de `storniert`)\n- **7** – `faulty` (de `fehlerhaft`)\n- **8** – `delivered` (de `zugestellt`) – registered mail only, final state\n- **9** – `returned to sender` (de `zurückgelaufen`) – registered mail only, final state", "type": "integer", "format": "int32" }, "text": { "description": "Plain-text status, returned in the account's language (e.g. `ready to ship` / German `versandbereit`). See field `code` for the fixed mapping.", "type": "string" } }, "example": { "code": 2, "text": "versandbereit" } }, "ResponseFormatEnum": { "description": "Defines the response format. Default is `FULL` (the response includes the validation result).\n\n`SHORT` returns the API response **immediately, without the validation result**; validation runs afterwards. Query the outcome via `GET /documents/status` or `GET /documents/{documentID}/status`.\n\n**Under high load** `FULL` requests are queued instead of rejected: the response can then take several minutes without any data being sent in between. Allow a client timeout of at least 15 minutes. If your client gives up earlier, the document is processed anyway – protect retries with an `Idempotency-Key` (`POST /sendings`) or with `externalReferenceIdUnique`. For large batches `SHORT` is the better choice.", "type": "string", "enum": [ "FULL", "SHORT" ], "default": "FULL", "example": "FULL" }, "Account": { "description": "Account data.", "type": "object", "required": [ "credit", "unit" ], "properties": { "credit": { "type": "integer", "format": "int32" }, "promotionCredit": { "type": "integer", "format": "int32" }, "creditLimit": { "type": "integer", "format": "int32" }, "unit": { "$ref": "#/definitions/CurrencyEnum" } } }, "Limits": { "description": "Effective bounds of this environment. A missing property means: no bound is configured for it.", "type": "object", "properties": { "maxRead": { "type": "integer", "format": "int32", "description": "Highest `limit` for `GET /documents`, `GET /sendings`, the journals and `GET /invoices/{invoiceNumber}` (default 500)." }, "maxReadStatus": { "type": "integer", "format": "int32", "description": "Highest `limit` for `GET /status`, `GET /documents/status`, `GET /sendings/status` and `GET /regmails/` (default 5000)." }, "maxSendings": { "type": "integer", "format": "int32", "description": "Highest number of `documentIds` per `POST /sendings` and `PUT /sendings` (default 500)." }, "maxDelete": { "type": "integer", "format": "int32", "description": "Highest number of `documentIds` per `DELETE /documents` and `DELETE /sendings` (default 250)." }, "maxUploadSize": { "type": "integer", "format": "int64", "description": "Largest accepted file per upload, in bytes (20 MB in production). Serial letters have their own limit, see `maxSerialLetterUploadSize`." }, "maxSerialLetterUploadSize": { "type": "integer", "format": "int64", "description": "Largest accepted file for a serial letter (`POST /documents` with `splitParams`), in bytes (default 60 MB)." }, "maxApiKeys": { "type": "integer", "format": "int32", "description": "Highest number of API keys per login; deactivated and expired keys count as well (default 10)." } } }, "ErrorParam": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string" }, "value": { "type": "string" } } }, "Content": { "description": "The file content and file name. The content must be Base64-encoded.", "type": "object", "required": [ "filename", "content" ], "properties": { "filename": { "type": "string" }, "content": { "type": "string", "format": "byte" } }, "example": { "filename": "musterbrief.pdf", "content": "" } }, "User": { "description": "The customer's personal data.", "type": "object", "required": [ "email" ], "properties": { "debitornumber": { "type": "string" }, "email": { "type": "string", "format": "email" }, "forename": { "type": "string" }, "surname": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "plz": { "type": "string" }, "state": { "type": "string" }, "country": { "type": "string" }, "organization": { "type": "string" }, "title": { "type": "string" }, "phone": { "type": "string" }, "partnerId": { "type": "string" } } }, "Coworker": { "description": "Data of a coworker (sub-user).", "type": "object", "required": [ "email" ], "properties": { "debitornumber": { "type": "string" }, "email": { "type": "string", "format": "email" }, "forename": { "type": "string" }, "surname": { "type": "string" }, "registrationDate": { "type": "string", "format": "date" }, "numberOfSendings": { "type": "integer", "format": "int32" }, "totalAmount": { "$ref": "#/definitions/Price" } } }, "CurrencyEnum": { "description": "Currency unit. `EUROCENT`: amounts are given in euro cents (e.g. `106` = 1.06 €).", "type": "string", "enum": [ "EUROCENT" ] }, "Address": { "description": "An address.", "type": "object", "required": [ "name", "street", "zipCode", "city" ], "properties": { "name": { "type": "string" }, "nameExtend": { "type": "string" }, "street": { "type": "string" }, "city": { "type": "string" }, "zipCode": { "type": "string" }, "country": { "type": "string" } } }, "Invoice": { "description": "An invoice.", "type": "object", "required": [ "id", "filename" ], "properties": { "id": { "type": "string" }, "filename": { "type": "string" }, "totalAmount": { "$ref": "#/definitions/Price" }, "date": { "type": "string", "format": "date" } } }, "Transaction": { "description": "A transaction – a single accounting entry (e.g. belonging to an invoice).", "type": "object", "required": [ "id", "action", "date" ], "properties": { "id": { "type": "string" }, "action": { "$ref": "#/definitions/Action" }, "date": { "type": "string", "format": "date" }, "documentId": { "type": "string" }, "filename": { "type": "string" }, "amount": { "$ref": "#/definitions/Price" }, "numberOfPages": { "type": "integer", "format": "int32" }, "options": { "$ref": "#/definitions/Options" }, "status": { "$ref": "#/definitions/Status" }, "coworker": { "description": "Debtor number (`debitornumber`) of the coworker the transaction belongs to.", "type": "string" } } }, "Action": { "description": "Describes an action of a transaction.", "type": "object", "required": [ "code", "text" ], "properties": { "code": { "description": "The following action codes are defined:\n- **1** – sent\n- **2** – cancelled\n- **3** – delivery error", "type": "integer", "format": "int32" }, "text": { "type": "string" } }, "example": { "code": 1, "text": "is sent" } }, "ApiKey": { "description": "An API key of a login, without the key itself (masked).", "type": "object", "required": [ "keyId", "name", "maskedKey", "scope", "status", "createdAt", "createdVia", "usedLast24h", "lockedBySupport", "lockedByOwner", "expiryReminder" ], "properties": { "keyId": { "type": "string", "description": "Public part of the key (12 characters); identifies the key in the URL." }, "name": { "type": "string", "maxLength": 64, "description": "Name of the key, unique per login (case-insensitive)." }, "maskedKey": { "type": "string", "description": "Masked key for recognition: `bnct__…`." }, "scope": { "$ref": "#/definitions/ApiKeyScopeEnum" }, "status": { "$ref": "#/definitions/ApiKeyStatusEnum" }, "allowedIps": { "type": "array", "items": { "type": "string" }, "description": "IP addresses or CIDR ranges the key may be used from (normalized). Missing: every address." }, "expiresAt": { "type": "string", "format": "date-time", "description": "Expiry; missing: the key does not expire." }, "createdAt": { "type": "string", "format": "date-time", "description": "Time of creation." }, "createdVia": { "$ref": "#/definitions/ApiKeyChannelEnum" }, "statusChangedAt": { "type": "string", "format": "date-time", "description": "Last deactivation or reactivation; missing: never." }, "statusChangedVia": { "$ref": "#/definitions/ApiKeyChannelEnum" }, "lastUsedAt": { "type": "string", "format": "date-time", "description": "Last successful use (updated about once a minute); missing: never used." }, "lastUsedIp": { "type": "string", "description": "Client IP address of the last successful use." }, "usedLast24h": { "type": "boolean", "description": "Was the key used successfully within the last 24 hours?" }, "lastRejectedAt": { "type": "string", "format": "date-time", "description": "Last request with the correct key that was rejected anyway (e.g. IP address not allowed, key deactivated or expired); missing: none." }, "lastRejectedIp": { "type": "string", "description": "Client IP address of that rejected request." }, "lastRejectedCode": { "type": "integer", "format": "int32", "description": "Error code of that rejected request (e.g. `44032`)." }, "lockedBySupport": { "type": "boolean", "description": "Deactivated by Binect customer service: cannot be reactivated." }, "lockedByOwner": { "type": "boolean", "description": "Locked by the main account of this login (coworker logins only): cannot be reactivated here, only the main account can release it." }, "expiryReminder": { "$ref": "#/definitions/ApiKeyExpiryReminder" } } }, "ApiKeyExpiryReminder": { "description": "E-mail reminders before an API key expires, plus one e-mail when it has expired; only for keys with an expiry date. The e-mails go to the e-mail address of the login and contain neither the key nor a link. Creating a key without `expiryReminder` switches the reminder on with `[30, 7, 1]`.", "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "description": "`false`: no reminder and no e-mail on expiry." }, "daysBefore": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 365 }, "maxItems": 3, "description": "Up to 3 points in time, in days before the expiry (1 to 365, e.g. `[30, 7, 1]`; duplicates count once); missing or empty: only the e-mail on expiry. Points already reached when the key is created or the reminder is changed are skipped; if several points become due at once, one e-mail goes out." } } }, "Authentication": { "description": "How a request was signed in.", "type": "object", "required": [ "email", "authMode", "method", "transport" ], "properties": { "email": { "type": "string", "format": "email", "description": "E-mail address of the login." }, "authMode": { "$ref": "#/definitions/AuthModeEnum" }, "method": { "$ref": "#/definitions/AuthMethodEnum" }, "transport": { "$ref": "#/definitions/AuthTransportEnum" }, "clientIp": { "type": "string", "description": "Client IP address as the server sees it; an IP allow list is checked against it. Missing: not known." }, "apiKey": { "$ref": "#/definitions/ApiKey" } } }, "ApiKeyScopeEnum": { "description": "Rights of an API key. `FULL`: everything the login may do. `READ_ONLY`: reading requests only (`GET`, `HEAD`, `OPTIONS`); anything else is rejected with `403` (error code `44033`).", "type": "string", "enum": [ "FULL", "READ_ONLY" ] }, "ApiKeyStatusEnum": { "description": "Status of an API key. `ACTIVE`: usable. `INACTIVE`: deactivated (by you or by Binect customer service). `EXPIRED`: past its expiry.", "type": "string", "enum": [ "ACTIVE", "INACTIVE", "EXPIRED" ] }, "ApiKeyChannelEnum": { "description": "Where a change to an API key came from. `PORTAL`: customer portal. `REST`: REST API, signed in with the password. `KEY`: REST API, signed in with this very key (self-deactivation). `OWNER`: the main account of this login (coworker logins). `ADMIN`: Binect customer service.", "type": "string", "enum": [ "PORTAL", "REST", "KEY", "OWNER", "ADMIN" ] }, "AuthModeEnum": { "description": "What the REST API accepts for this login. `PASSWORD`: e-mail and password only (default). `PASSWORD_AND_KEY`: password and API keys. `KEY_ONLY`: API keys only. The mode is chosen in the customer portal under **Mein Konto → API-Keys**; the customer portal and the SOAP interface always use the password.", "type": "string", "enum": [ "PASSWORD", "PASSWORD_AND_KEY", "KEY_ONLY" ] }, "AuthMethodEnum": { "description": "Sign-in method of a request. `PASSWORD`: e-mail and password. `API_KEY`: an API key.", "type": "string", "enum": [ "PASSWORD", "API_KEY" ] }, "AuthTransportEnum": { "description": "How the credentials were sent. `BASIC`: HTTP Basic with e-mail and password. `BEARER`: `Authorization: Bearer `. `X_API_KEY`: `X-API-Key: `. `BASIC_BRIDGE`: the API key in an HTTP Basic sign-in. `RAW`: `Authorization: ` without a scheme.", "type": "string", "enum": [ "BASIC", "BEARER", "X_API_KEY", "BASIC_BRIDGE", "RAW" ] } } }