{"openapi":"3.1.0","info":{"title":"Macaaw Public API","version":"1.0.0","description":"Documents for signature, PDF tasks and webhooks. Authenticate with `Authorization: API-Key <key>`. Pages: `?page=1&count=50` (max 100). Errors: `{ type, code, detail }`.","contact":{"url":"https://macaaw.com/developers"}},"servers":[{"url":"https://macaaw.com/public/v1"}],"security":[{"ApiKey":[]}],"tags":[{"name":"Documents"},{"name":"Tasks"},{"name":"Invoice checks"},{"name":"Webhooks"},{"name":"Meta"}],"paths":{"/openapi.json":{"get":{"operationId":"getOpenApi","tags":["Meta"],"summary":"This OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 JSON"}},"security":[]}},"/documents":{"post":{"operationId":"createDocument","tags":["Documents"],"summary":"Create a document from a PDF","description":"Multipart: `file` (PDF) and `data` (JSON string). Text tags such as `{signature:Client}` become fields (parse_text_tags, default true); AcroForm fields named `Role.something` become fields with parse_form_fields. Unknown role → 400.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the first response for 24 hours."}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreated"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"File too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":100,"sandbox":10,"windowSeconds":60},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["data","file"],"properties":{"file":{"type":"string","format":"binary"},"data":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":255},"recipients":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":254},"first_name":{"type":"string","maxLength":50},"last_name":{"type":"string","maxLength":50},"role":{"type":"string","minLength":1,"maxLength":60,"pattern":"^[^{}*:.\\n]+$"},"signing_order":{"type":"integer","minimum":1,"maximum":100},"locale":{"type":"string","enum":["en","zh","hi","es","ar","fr","bn","pt","id","ur","ru","de","ja","pcm","arz","mr","vi","te","sw","ha","tr","pnb","tl","ta"]},"type":{"type":"string","enum":["signer","cc"]}},"required":["email","role"],"additionalProperties":false},"minItems":1,"maxItems":50},"fields":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","name","date","text","checkbox"]},"role":{"type":"string","minLength":1,"maxLength":60},"page":{"type":"integer","minimum":1,"maximum":500},"x":{"type":"number","minimum":0,"maximum":100000},"y":{"type":"number","minimum":0,"maximum":100000},"width":{"type":"number","minimum":0,"maximum":100000},"height":{"type":"number","minimum":0,"maximum":100000},"required":{"type":"boolean"},"name":{"type":"string","maxLength":100}},"required":["type","role","page","x","y","width","height"],"additionalProperties":false},"maxItems":500},"parse_form_fields":{"type":"boolean"},"parse_text_tags":{"type":"boolean"},"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":2000},"expires_in_days":{"enum":[7,14,30]},"reminders":{"type":"boolean"},"access_code":{"type":"string","minLength":4,"maxLength":32},"tags":{"type":"array","items":{"type":"string","minLength":1,"maxLength":50},"maxItems":20},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500}}},"required":["name","recipients"],"additionalProperties":false,"description":"JSON string"}}},"encoding":{"data":{"contentType":"application/json"}}}}}},"get":{"operationId":"listDocuments","tags":["Documents"],"summary":"List documents","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["document.uploaded","document.draft","document.sent","document.viewed","document.completed","document.declined","document.voided","document.expired","document.error"]}},{"name":"tag","in":"query","required":false,"schema":{"type":"string","maxLength":50}},{"name":"created_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]}},{"name":"created_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"}]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100000,"default":1}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"order_by","in":"query","required":false,"schema":{"type":"string","enum":["date_created","-date_created"],"default":"-date_created"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":600,"sandbox":10,"windowSeconds":60}}},"/documents/{id}":{"get":{"operationId":"getDocumentStatus","tags":["Documents"],"summary":"Document status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentStatus"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":600,"sandbox":10,"windowSeconds":60}},"delete":{"operationId":"deleteDocument","tags":["Documents"],"summary":"Delete a document now (files and records)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":600,"sandbox":10,"windowSeconds":60}}},"/documents/{id}/details":{"get":{"operationId":"getDocumentDetails","tags":["Documents"],"summary":"Document details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentDetails"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":300,"sandbox":10,"windowSeconds":60}}},"/documents/{id}/send":{"post":{"operationId":"sendDocument","tags":["Documents"],"summary":"Send a draft for signature","description":"`silent: true` sends no emails; use embedded signing sessions. 409 unless the document is a draft.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the first response for 24 hours."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentStatus"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":100,"sandbox":10,"windowSeconds":60},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","maxLength":200},"message":{"type":"string","maxLength":2000},"silent":{"type":"boolean"}},"additionalProperties":false}}}}}},"/documents/{id}/remind":{"post":{"operationId":"remindDocument","tags":["Documents"],"summary":"Remind signers","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RemindResult"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":100,"sandbox":10,"windowSeconds":60},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id":{"type":"string","format":"uuid"}},"additionalProperties":false}}}}}},"/documents/{id}/status":{"patch":{"operationId":"changeDocumentStatus","tags":["Documents"],"summary":"Void a sent document","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentStatus"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":100,"sandbox":10,"windowSeconds":60},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"const":"document.voided"},"note":{"type":"string","maxLength":500}},"required":["status"],"additionalProperties":false}}}}}},"/documents/{id}/download":{"get":{"operationId":"downloadDocument","tags":["Documents"],"summary":"Download the PDF","description":"Completed: the signed PDF with its signing certificate. Otherwise the original. 409 while the signed PDF is being prepared.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"separate_certificate","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}}],"responses":{"200":{"description":"File","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":100,"sandbox":10,"windowSeconds":60}}},"/documents/{id}/session":{"post":{"operationId":"createSigningSession","tags":["Documents"],"summary":"Embedded signing session","description":"For a sent document (silent or not). Open `url` in an iframe on one of your allowed embed origins; the page posts `{ type: \"macaaw.signing\", event: \"completed\"|\"declined\" }` to the parent.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the first response for 24 hours."}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":100,"sandbox":10,"windowSeconds":60},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"recipient":{"type":"string","format":"email","maxLength":254},"lifetime":{"type":"integer","minimum":900,"maximum":86400}},"required":["recipient"],"additionalProperties":false}}}}}},"/tools":{"get":{"operationId":"listTools","tags":["Tasks"],"summary":"Tools available through the API","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":600,"sandbox":10,"windowSeconds":60}}},"/tasks":{"post":{"operationId":"createTask","tags":["Tasks"],"summary":"Run a server tool","description":"Multipart: `files[]` and `data` ({ tool, options }). The task is queued at once.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the first response for 24 hours."}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"File too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":120,"sandbox":10,"windowSeconds":60},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["data","files[]"],"properties":{"files[]":{"type":"array","items":{"type":"string","format":"binary"}},"data":{"type":"object","properties":{"tool":{"type":"string","minLength":1,"maxLength":60},"options":{"type":"object","additionalProperties":{}}},"required":["tool"],"additionalProperties":false,"description":"JSON string"}}},"encoding":{"data":{"contentType":"application/json"}}}}}}},"/tasks/{id}":{"get":{"operationId":"getTask","tags":["Tasks"],"summary":"Task status","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Task"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":600,"sandbox":10,"windowSeconds":60}},"delete":{"operationId":"deleteTask","tags":["Tasks"],"summary":"Delete the task files now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":600,"sandbox":10,"windowSeconds":60}}},"/tasks/{id}/download":{"get":{"operationId":"downloadTask","tags":["Tasks"],"summary":"Download the result (a ZIP when there are several files)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"File","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":100,"sandbox":10,"windowSeconds":60}}},"/invoice-checks":{"post":{"operationId":"createInvoiceCheck","tags":["Invoice checks"],"summary":"Check a supplier invoice against its PO and delivery note","description":"Business plan. Multipart: `files[]` (the invoice, purchase order and delivery note: PDF, JPEG or PNG; up to 10) and `data` ({ kinds? }). One invoice check is charged (allowance, then 5 credits). The documents are read at once; a person approves in the account area. Live keys only.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the first response for 24 hours."}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCheck"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"File too large","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Unprocessable file","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":120,"sandbox":10,"windowSeconds":60},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["data","files[]"],"properties":{"files[]":{"type":"array","items":{"type":"string","format":"binary"}},"data":{"type":"object","properties":{"kinds":{"type":"array","items":{"type":"string","enum":["invoice","purchase_order","delivery_note","credit_note"]},"maxItems":10,"description":"Kind of each file in files[], in the same order; left out (or shorter than files[]) means detect it."}},"additionalProperties":false,"description":"JSON string"}}},"encoding":{"data":{"contentType":"application/json"}}}}}}},"/invoice-checks/{id}":{"get":{"operationId":"getInvoiceCheck","tags":["Invoice checks"],"summary":"Invoice check status and result","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvoiceCheck"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":600,"sandbox":10,"windowSeconds":60}}},"/webhook-subscriptions":{"post":{"operationId":"createWebhookSubscription","tags":["Webhooks"],"summary":"Create a webhook subscription","description":"https only, public hosts only (private, loopback, link-local and metadata addresses are refused). The shared key is shown once.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Replays the first response for 24 hours."}],"responses":{"201":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionCreated"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","format":"uri","maxLength":2048},"triggers":{"type":"array","items":{"type":"string","enum":["document_state_changed","recipient_completed","document_completed_pdf_ready","document_updated","document_deleted","document_creation_failed","task_completed","task_failed"]},"minItems":1,"maxItems":8},"active":{"type":"boolean"},"sandbox":{"type":"boolean"}},"required":["name","url","triggers"],"additionalProperties":false}}}}},"get":{"operationId":"listWebhookSubscriptions","tags":["Webhooks"],"summary":"List webhook subscriptions","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscriptionList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60}}},"/webhook-subscriptions/{uuid}":{"get":{"operationId":"getWebhookSubscription","tags":["Webhooks"],"summary":"Get a webhook subscription","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60}},"patch":{"operationId":"updateWebhookSubscription","tags":["Webhooks"],"summary":"Update a webhook subscription","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"url":{"type":"string","format":"uri","maxLength":2048},"triggers":{"type":"array","items":{"type":"string","enum":["document_state_changed","recipient_completed","document_completed_pdf_ready","document_updated","document_deleted","document_creation_failed","task_completed","task_failed"]},"minItems":1,"maxItems":8},"active":{"type":"boolean"}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteWebhookSubscription","tags":["Webhooks"],"summary":"Delete a webhook subscription","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No content"},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60}}},"/webhook-subscriptions/{uuid}/shared-key":{"post":{"operationId":"regenerateWebhookSharedKey","tags":["Webhooks"],"summary":"Regenerate the shared key","parameters":[{"name":"uuid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SharedKey"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60}}},"/webhook-events":{"get":{"operationId":"listWebhookEvents","tags":["Webhooks"],"summary":"Delivery history","parameters":[{"name":"subscription","in":"query","required":false,"schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","delivered","failed"]}},{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100000,"default":1}},{"name":"count","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEventList"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60}}},"/webhook-events/{id}/resend":{"post":{"operationId":"resendWebhookEvent","tags":["Webhooks"],"summary":"Resend a delivery now","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, unknown or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan or permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Wrong state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"}}}}},"x-rate-limit":{"live":60,"sandbox":10,"windowSeconds":60}}}},"webhooks":{"event":{"post":{"summary":"Event delivery","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}},"responses":{"200":{"description":"Any status below 400 counts as delivered; 410 deactivates the subscription."}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"API-Key mk_live_… or API-Key mk_test_… (sandbox)"}},"schemas":{"Error":{"type":"object","required":["type","code","detail"],"properties":{"type":{"type":"string","enum":["request_error","authentication_error","permission_error","not_found","rate_limit","limit_error","conflict","server_error"]},"code":{"type":"string","description":"Macaaw error code, e.g. LIMIT_AGREEMENTS, VALIDATION, API_KEY_INVALID."},"detail":{"type":"string","description":"English message."},"info":{"type":"object","description":"Machine-readable extras (e.g. reason, limit, fields)."}}},"DocumentStatus":{"type":"object","required":["id","name","status","date_created"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["document.uploaded","document.draft","document.sent","document.viewed","document.completed","document.declined","document.voided","document.expired","document.error"]},"date_created":{"type":["string","null"],"format":"date-time"},"date_modified":{"type":["string","null"],"format":"date-time"},"expiration_date":{"type":["string","null"],"format":"date-time"},"sandbox":{"type":"boolean"}}},"DocumentCreated":{"allOf":[{"$ref":"#/components/schemas/DocumentStatus"},{"type":"object","properties":{"uuid":{"type":"string"},"status":{"const":"document.uploaded"}}}]},"Recipient":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"role":{"type":"string"},"type":{"type":"string","enum":["signer","cc"]},"signing_order":{"type":"integer"},"has_completed":{"type":"boolean"},"status":{"type":"string","enum":["waiting","sent","viewed","completed","declined"]},"completed_at":{"type":["string","null"],"format":"date-time"},"viewed_at":{"type":["string","null"],"format":"date-time"},"declined_at":{"type":["string","null"],"format":"date-time"}}},"Field":{"type":"object","description":"Box in PDF points; origin at the top-left of the page as displayed.","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["signature","initials","name","date","text","checkbox"]},"recipient_id":{"type":"string"},"role":{"type":["string","null"]},"page":{"type":"integer","minimum":1},"x":{"type":"number"},"y":{"type":"number"},"width":{"type":"number"},"height":{"type":"number"},"required":{"type":"boolean"},"name":{"type":["string","null"]},"filled":{"type":"boolean"}}},"DocumentDetails":{"allOf":[{"$ref":"#/components/schemas/DocumentStatus"},{"type":"object","properties":{"date_sent":{"type":["string","null"],"format":"date-time"},"date_completed":{"type":["string","null"],"format":"date-time"},"subject":{"type":["string","null"]},"message":{"type":["string","null"]},"signing_order":{"type":"string","enum":["sequential","parallel"]},"silent":{"type":"boolean"},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"}},"tags":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"events":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"date":{"type":["string","null"],"format":"date-time"},"recipient_id":{"type":["string","null"]}}}},"sent_by":{"type":["object","null"],"properties":{"email":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"}}},"download_available":{"type":"boolean"}}}]},"DocumentList":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/DocumentStatus"}}}},"RemindResult":{"type":"object","properties":{"reminded":{"type":"array","items":{"type":"string"}},"skipped":{"type":"array","items":{"type":"object","properties":{"recipient_id":{"type":"string"},"reason":{"type":"string"}}}}}},"Session":{"type":"object","required":["id","expires_at","url"],"properties":{"id":{"type":"string"},"expires_at":{"type":["string","null"],"format":"date-time"},"url":{"type":"string","format":"uri"}}},"Tool":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"runs_on":{"type":"string","enum":["server","browser"]},"api":{"type":"boolean"},"accepts":{"type":"array","items":{"type":"string"}},"max_files":{"type":["integer","null"]},"min_files":{"type":"integer"},"plan":{"type":"string","enum":["free","pro"]},"beta":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"type":{"type":"string"},"choices":{"type":"array"},"default":{},"min":{"type":"number"},"max":{"type":"number"},"required":{"type":"boolean"}}}}}},"ToolList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}}}},"Task":{"type":"object","required":["id","tool","status"],"properties":{"id":{"type":"string"},"tool":{"type":"string"},"status":{"type":"string","enum":["task.queued","task.processing","task.completed","task.failed","task.deleted"]},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"detail":{"type":["string","null"]}}},"input_size":{"type":"integer"},"output_size":{"type":["integer","null"]},"output_files":{"type":["integer","null"]},"stats":{"type":["object","null"]},"sandbox":{"type":"boolean"},"date_created":{"type":["string","null"],"format":"date-time"},"date_completed":{"type":["string","null"],"format":"date-time"},"expires_at":{"type":["string","null"],"format":"date-time"}}},"InvoiceCheck":{"type":"object","required":["id","status"],"description":"Money in integer pence. Poll until no document is reading.","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["received","reading","matched","needs_review","waiting_po","waiting_dn","on_hold","rejected","approved","awaiting_credit","exported"]},"supplier":{"type":["string","null"]},"invoice_number":{"type":["string","null"]},"po_number":{"type":["string","null"]},"dn_number":{"type":["string","null"]},"invoice_date":{"type":["string","null"]},"due_date":{"type":["string","null"]},"currency":{"type":"string"},"invoiced_total_pence":{"type":["integer","null"]},"matched_total_pence":{"type":["integer","null"]},"difference_pence":{"type":["integer","null"]},"issues":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"line":{"type":"integer"},"amount_pence":{"type":"integer"},"detail":{"type":"string"}}}},"decision":{"type":["string","null"],"enum":[null,"approve_matched","approve_invoiced","hold","reject"]},"approved_amount_pence":{"type":["integer","null"]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":["string","null"],"enum":[null,"invoice","purchase_order","delivery_note","credit_note"]},"status":{"type":"string","enum":["pending","reading","read","failed"]}}}},"lines":{"type":"array","items":{"type":"object","properties":{"position":{"type":"integer"},"description":{"type":"string"},"result":{"type":"string"},"amount_at_stake_pence":{"type":"integer"}}}},"url":{"type":"string","format":"uri","description":"The check in the account area (people approve there)."},"date_created":{"type":["string","null"],"format":"date-time"},"date_modified":{"type":["string","null"],"format":"date-time"}}},"WebhookSubscription":{"type":"object","properties":{"uuid":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"triggers":{"type":"array","items":{"type":"string","enum":["document_state_changed","recipient_completed","document_completed_pdf_ready","document_updated","document_deleted","document_creation_failed","task_completed","task_failed"]}},"active":{"type":"boolean"},"sandbox":{"type":"boolean"},"deactivated_reason":{"type":["string","null"],"enum":[null,"gone_410","manual"]},"date_created":{"type":["string","null"],"format":"date-time"},"date_modified":{"type":["string","null"],"format":"date-time"}}},"WebhookSubscriptionCreated":{"allOf":[{"$ref":"#/components/schemas/WebhookSubscription"},{"type":"object","properties":{"shared_key":{"type":"string","description":"Shown once."}}}]},"WebhookSubscriptionList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/WebhookSubscription"}}}},"SharedKey":{"type":"object","properties":{"uuid":{"type":"string"},"shared_key":{"type":"string"}}},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"subscription":{"type":"string"},"event":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"status":{"type":"string","enum":["pending","delivered","failed"]},"attempts":{"type":"integer"},"http_status":{"type":["integer","null"]},"error":{"type":["string","null"]},"response":{"type":["string","null"],"description":"First 1 KB of the answer."},"date_created":{"type":["string","null"],"format":"date-time"},"delivered_at":{"type":["string","null"],"format":"date-time"},"next_attempt_at":{"type":["string","null"],"format":"date-time"}}},"WebhookEventList":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}}}},"WebhookPayload":{"type":"array","description":"POSTed to the subscription URL with ?signature=<hex HMAC-SHA256(shared_key, raw body)>.","items":{"type":"object","properties":{"event":{"type":"string","enum":["document_state_changed","recipient_completed","document_completed_pdf_ready","document_updated","document_deleted","document_creation_failed","task_completed","task_failed","test"]},"data":{"description":"Same shape as /documents/{id}/details or /tasks/{id}."}}}}}}}