{"components":{"schemas":{"Error":{"properties":{"error":{"properties":{"code":{"type":"string"},"message":{"type":"string"}},"type":"object"},"request_id":{"type":"string"}},"type":"object"}},"securitySchemes":{"bearer":{"scheme":"bearer","type":"http"}}},"info":{"description":"Send documents for signature and get back sealed PDFs with a full evidence record.","title":"DocuInked API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/v1/accounts":{"get":{"description":"Lists the sub-accounts this account manages, for platforms.","operationId":"list_accounts","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List sub-accounts"},"post":{"description":"For platforms: makes an account for one of your customers. Act for it on any call with the header DocuInked-Account and your own key. Each has its own documents, branding and webhooks.","operationId":"create_account","parameters":[{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"name":{"maxLength":120,"type":"string"}},"required":["name"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Create a sub-account"}},"/v1/branding":{"get":{"description":"Shows the account's signer-facing name, accent colour, logo, embed origins and whether docuinked branding is hidden.","operationId":"get_branding","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get branding"},"post":{"description":"Sets what signers see: your name, accent colour, logo, and the sites allowed to embed signing. Fields you leave out stay as they are.","operationId":"update_branding","parameters":[{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"accent_color":{"pattern":"^#[0-9A-Fa-f]{6}$","type":"string"},"display_name":{"maxLength":80,"type":"string"},"embed_origins":{"description":"Sites allowed to frame signing, like https://app.example.com.","items":{"type":"string"},"maxItems":10,"type":"array"},"hide_docuinked_branding":{"type":"boolean"},"logo_png_base64":{"description":"PNG under 200 KB.","type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Update branding"}},"/v1/documents":{"get":{"description":"Lists documents in the current mode (test or live), newest first, with each signer's status. Filter by status; limit is 1 to 100.","operationId":"list_documents","parameters":[{"in":"query","name":"limit","schema":{"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"starting_after","schema":{"description":"Pass next_starting_after from the previous page.","type":"string"}},{"in":"query","name":"status","schema":{"enum":["draft","pending_approval","sent","sealing","completed","declined","voided","expired"]}},{"in":"query","name":"updated_since","schema":{"description":"Only documents changed since this time.","format":"date-time","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List documents"},"post":{"description":"Creates a draft from a PDF (pdf_url, pdf_base64, or several files) with signers and fields. Fields go after anchor text, on {{signature:1}} tags in the PDF, or at page coordinates; with none, fields go on the PDF's own Signature, Date and Name lines (one signer per signature line, placement: labels), or else one signature field per signer on the last page. Returns draft_hash, review_url, warnings and next_action. Sending is a separate step: send_document with the draft_hash.","operationId":"create_document","parameters":[{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"consumer_disclosure":{"description":"Signers are consumers: shows the ESIGN consumer disclosure and asks them to open a test PDF. Default false.","type":"boolean"},"expires_in_days":{"description":"Default 30.","maximum":365,"minimum":1,"type":"integer"},"fields":{"description":"Leave out to use the PDF's Signature, Date and Name lines, or else one signature field per signer on the last page.","items":{"additionalProperties":false,"properties":{"anchor":{"description":"Text in the PDF to place the field just after, such as 'Signature:'. Easier than coordinates.","type":"string"},"h":{"description":"Height as a fraction of page height. Has a sensible default per kind.","type":"number"},"kind":{"enum":["signature","initials","date","name","text","checkbox","dropdown","radio","attachment"]},"label":{"description":"Shown to the signer, such as 'Upload a photo ID'.","maxLength":80,"type":"string"},"options":{"description":"Choices for dropdown and radio fields.","items":{"maxLength":60,"type":"string"},"maxItems":20,"type":"array"},"page":{"description":"Needed with x and y. Left out when using anchor.","minimum":1,"type":"integer"},"required":{"type":"boolean"},"signer":{"description":"1 for the first signer in the list, 2 for the second.","minimum":1,"type":"integer"},"w":{"description":"Width as a fraction of page width. Has a sensible default per kind.","type":"number"},"x":{"description":"Left edge as a fraction of page width.","maximum":1,"minimum":0,"type":"number"},"y":{"description":"Top edge as a fraction of page height.","maximum":1,"minimum":0,"type":"number"}},"required":["signer","kind"],"type":"object"},"type":"array"},"files":{"description":"Several PDFs or images joined into one document, in order. Each item has url or base64.","items":{"additionalProperties":false,"properties":{"base64":{"type":"string"},"url":{"type":"string"}},"type":"object"},"maxItems":20,"type":"array"},"message":{"description":"Note shown in the signing email.","maxLength":2000,"type":"string"},"metadata":{"description":"Your own keys and values, returned on reads and webhooks' document lookups.","type":"object"},"ordered":{"description":"Sign one at a time in list order.","type":"boolean"},"pdf_base64":{"type":"string"},"pdf_url":{"description":"Public https link to the PDF.","type":"string"},"reminder_every_days":{"description":"0 turns reminders off. Default 3.","maximum":30,"minimum":0,"type":"integer"},"send":{"description":"Also send, under this key's send policy. Default false.","type":"boolean"},"signers":{"items":{"additionalProperties":false,"properties":{"access_code":{"description":"Optional code shared with the signer outside email.","type":"string"},"email":{"format":"email","type":"string"},"name":{"maxLength":120,"type":"string"},"role":{"description":"cc gets the finished copy and never signs. Default signer.","enum":["signer","cc"]}},"required":["name","email"],"type":"object"},"maxItems":10,"minItems":1,"type":"array"},"title":{"maxLength":200,"type":"string"}},"required":["title","signers"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Create a document"}},"/v1/documents/{id}":{"delete":{"description":"Permanently deletes a document that isn't in progress: its encryption key is destroyed, so its files can never be read again. The evidence log keeps a record that it existed. Not available to agent keys.","operationId":"delete_document","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Delete a document"},"get":{"description":"Shows one document's status, each signer's progress and its review link.","operationId":"get_document","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get a document"}},"/v1/documents/{id}/attachments/{field}":{"get":{"description":"Returns a file a signer uploaded, as base64, with its name, type and SHA-256. Field IDs are listed in get_evidence.","operationId":"get_attachment","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"field","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get a signer's upload"}},"/v1/documents/{id}/evidence":{"get":{"description":"Returns the full audit trail: every event, its hash chain, and the seal certificate.","operationId":"get_evidence","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get the evidence record"}},"/v1/documents/{id}/original_pdf":{"get":{"description":"Returns the document as it was uploaded, before any signature, as base64 with its SHA-256. Use it to preview a draft or a document in progress.","operationId":"get_original_pdf","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get the original PDF"}},"/v1/documents/{id}/remind":{"post":{"description":"Emails a reminder now to every signer of a sent document who hasn't signed yet. Returns how many were reminded.","operationId":"remind_signers","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Remind signers"}},"/v1/documents/{id}/send":{"post":{"description":"Asks to send a draft to its signers. The draft_hash must match the current draft. With an agent key or an MCP connection, nothing is sent: it creates an approval request and returns approval_url, and the document goes out only after a named person approves that exact draft (in test mode, simulate_approval can stand in for the person). In test mode no email is sent, signers at sign@test.docuinked.com or decline@test.docuinked.com act at once, and signing links come back.","operationId":"send_document","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"draft_hash":{"description":"From create_document. Refuses if the draft has changed since. Required for agent keys.","type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Send for signature"}},"/v1/documents/{id}/signed_pdf":{"get":{"description":"Returns the sealed, signed PDF as base64 with its SHA-256, once the document is completed. The file can be large.","operationId":"get_signed_pdf","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Get the signed PDF"}},"/v1/documents/{id}/signers/{position}":{"post":{"description":"Corrects the name or email of someone who hasn't signed yet, on a sent document. Old links stop working and a new request goes to the new address.","operationId":"update_signer","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"in":"path","name":"position","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"email":{"type":"string"},"name":{"maxLength":120,"type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Fix a recipient"}},"/v1/documents/{id}/signing_links":{"post":{"description":"Makes a signing link for one signer of a sent document, for your own app or message. With embed true it returns embed_url for an iframe on a site listed in your branding. Anyone holding the link can sign as that signer. Live agent keys and MCP connections can't create links for live documents.","operationId":"create_signing_link","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"embed":{"type":"boolean"},"signer":{"minimum":1,"type":"integer"}},"required":["signer"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Create a signing link"}},"/v1/documents/{id}/template":{"post":{"description":"Makes a reusable template from a draft or finished document: same file, fields and signer roles, with names and emails cleared.","operationId":"create_template","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"title":{"maxLength":200,"type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Save as a template"}},"/v1/documents/{id}/void":{"post":{"description":"Cancels a sent document that is still waiting for signatures, so it can no longer be signed. This can't be undone.","operationId":"void_document","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"reason":{"description":"Optional. Kept in the evidence log and shown in the document's history.","maxLength":500,"type":"string"}},"required":[],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Void a document"}},"/v1/templates":{"get":{"description":"Lists reusable templates with their IDs and signer roles, for create_from_template.","operationId":"list_templates","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List templates"}},"/v1/templates/{id}/bulk":{"post":{"description":"Creates and sends one document per recipient set from a template, up to 100 at a time. With agent keys and MCP connections, each live document waits for its own approval. Over REST, an Idempotency-Key makes retries safe.","operationId":"bulk_send","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"recipients":{"items":{"additionalProperties":false,"properties":{"metadata":{"type":"object"},"signers":{"items":{"additionalProperties":false,"properties":{"access_code":{"description":"Optional code shared with the signer outside email.","type":"string"},"email":{"format":"email","type":"string"},"name":{"maxLength":120,"type":"string"},"role":{"description":"cc gets the finished copy and never signs. Default signer.","enum":["signer","cc"]}},"required":["name","email"],"type":"object"},"maxItems":10,"minItems":1,"type":"array"},"title":{"maxLength":200,"type":"string"}},"required":["signers"],"type":"object"},"maxItems":100,"minItems":1,"type":"array"}},"required":["recipients"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Bulk send a template"}},"/v1/templates/{id}/documents":{"post":{"description":"Creates a draft from a template, filling its signer roles in order. Nothing is sent.","operationId":"create_from_template","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"signers":{"items":{"additionalProperties":false,"properties":{"access_code":{"description":"Optional code shared with the signer outside email.","type":"string"},"email":{"format":"email","type":"string"},"name":{"maxLength":120,"type":"string"},"role":{"description":"cc gets the finished copy and never signs. Default signer.","enum":["signer","cc"]}},"required":["name","email"],"type":"object"},"maxItems":10,"minItems":1,"type":"array"},"title":{"maxLength":200,"type":"string"}},"required":["signers"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Start from a template"}},"/v1/test/documents/{id}/approve":{"post":{"description":"Test mode only. Approves a test document's pending approval as the account's person would, then sends it, so CI and agent evals can run the approval step unattended. Live documents always need a person to approve at approval_url.","operationId":"simulate_approval","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Simulate the approval (test)"}},"/v1/test/documents/{id}/simulate":{"post":{"description":"Test mode only. Signs or declines as one signer (signer is their position, from 1) so a whole flow runs without a browser.","operationId":"simulate_signer","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"action":{"enum":["sign","decline"]},"signer":{"minimum":1,"type":"integer"}},"required":["signer","action"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Simulate a signer (test)"}},"/v1/webhooks":{"get":{"description":"Lists active webhooks.","operationId":"list_webhooks","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"List webhooks"},"post":{"description":"Registers an https URL for events such as document.completed. Returns the signing secret once.","operationId":"create_webhook","parameters":[{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"events":{"description":"Only these events. Leave out for all.","items":{"type":"string"},"type":"array"},"url":{"type":"string"}},"required":["url"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Add a webhook"}},"/v1/webhooks/{id}":{"delete":{"description":"Stops sending events to a webhook.","operationId":"delete_webhook","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Remove a webhook"}},"/v1/webhooks/{id}/deliveries":{"get":{"description":"The last 50 delivery attempts for a webhook: event, status code, error and time taken.","operationId":"list_webhook_deliveries","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Webhook delivery log"}},"/v1/webhooks/{id}/test":{"post":{"description":"Sends a signed test event to the webhook right away and reports what the endpoint answered.","operationId":"test_webhook","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"Safe retries: the same key returns the first result.","in":"header","name":"Idempotency-Key","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Send a test event"}},"/v1/whoami":{"get":{"description":"Confirms the connection works. Shows the account name, whether it is in test mode (no email is ever sent) or live, and the daily limit on live sends.","operationId":"whoami","parameters":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"Success"},"default":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"Error"}},"summary":"Check connection"}}},"security":[{"bearer":[]}],"servers":[{"url":"https://docuinked.com"}]}