{"openapi":"3.1.0","info":{"title":"DoConure","description":"Compose documents from structured data, send them for electronic signature, and run both in one call. Every failure carries a stable code and a permanent four-digit number; every mutating call accepts an Idempotency-Key; every response carries an X-Request-Id. Every JSON answer for an operation carries output.credits: {used, left} - what that operation settled, and what the account has left, read from the ledger after it settled (a PDF answer carries the same two numbers in X-Credits-Used and X-Credits-Left). Bulk composition under /api/v1/bulk is asynchronous (compose, sign, CSV or JSONL input, a ZIP of the results, a completion webhook, a retry of the failed items): a batch is admitted whole or refused whole, answers 202 with a job in output.bulk, and only delivered documents are charged. Signer Fly signs a document composed here or a PDF you upload once (POST /api/v1/sign/files, then name its fileId in an envelope); the signer opens a link hosted by DoConure at a secure public URL - there is no embedded or iframe signing. Before sending, POST /api/v1/compose/documents/validate answers what a generate call would find and roughly what it costs, charging nothing; files are uploaded once and used by id (/api/v1/compose/files); a document can be handed to someone without a key through a signed, expiring, revocable address (/dl/{token}). Every operation lists the Bearer scope it needs and answers failures with the ApiError envelope. The guide is at /docs/.","version":"v1"},"paths":{"/api/v1/sign/envelopes":{"post":{"tags":["signatures"],"summary":"Create Envelope","description":"Draft a signing transaction. Nothing is sent and nothing is charged -\nunless `?send=true`, which creates **and sends** in one call (the same two\nsteps, `envelopes.create_and_send`, that bulk signing will use): the\none-call form of `existing PDF -> signature`.\n\nIdempotent even so. Nothing is charged here, but a retried draft leaves a\nsecond envelope behind — and the caller then sends the one it knows\nabout while the other sits in the console forever, which is the kind of\nmess somebody has to clean up by hand. With `send=true` it is also the\nbillable moment, which makes the key more important, not less.\n\n`settings.isTest` needs the `isTest` token scope, like a test composition.\nSources are `documentId`, `fileId` (`POST /files`) or the inline\n`fileBase64`; see `schemas.DocumentRef`.","operationId":"create_envelope_api_v1_sign_envelopes_post","parameters":[{"name":"send","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Send"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnvelopeCreateRequest"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Envelope Api V1 Sign Envelopes Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"},"get":{"tags":["signatures"],"summary":"List Envelopes","operationId":"list_envelopes_api_v1_sign_envelopes_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","description":"`all`, `production` or `test`; anything else is `all`. Test and production are never one list unless you ask for it.","default":"all","title":"Kind"},"description":"`all`, `production` or `test`; anything else is `all`. Test and production are never one list unless you ask for it."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Envelopes Api V1 Sign Envelopes Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/files":{"post":{"tags":["signatures"],"summary":"Upload Source File","description":"Upload a PDF to sign. Answers a `fileId` to name in an envelope's\n`settings.documents`; **charges nothing** (the signature is charged at\n`send`).\n\nValidated whole before anything is stored - magic bytes, structure, size,\npage count, encryption and active content (`FILE_REJECTED`,\n`details.reason`). The file lands in the same store as Composer Fly's\n(`composer.stored_files`), so **identical bytes are one file**: uploading a\nPDF the organisation already holds answers **200** with the existing\n`fileId` instead of **201** and a second copy. Send an `Idempotency-Key`.","operationId":"upload_source_file_api_v1_sign_files_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SourceFileRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Upload Source File Api V1 Sign Files Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]},"get":{"tags":["signatures"],"summary":"List Source Files","description":"The organisation's live PDFs that can be signed, newest first.","operationId":"list_source_files_api_v1_sign_files_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":100,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Source Files Api V1 Sign Files Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/files/{file_id}":{"get":{"tags":["signatures"],"summary":"Read Source File","description":"One source file's facts (never its bytes: the file is the customer's own\nand was handed to this service to be signed, not to be handed back).","operationId":"read_source_file_api_v1_sign_files__file_id__get","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","title":"File Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Read Source File Api V1 Sign Files  File Id  Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"},"delete":{"tags":["signatures"],"summary":"Delete Source File","description":"Delete a source file nobody needs. `STORED_FILE_IN_USE` while an open\nenvelope still names it. Envelopes already finished keep what they signed:\ntheir own record pins the file's `sha256`, and the bytes stay for their\nevidence bundle until its retention ends.","operationId":"delete_source_file_api_v1_sign_files__file_id__delete","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","title":"File Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Source File Api V1 Sign Files  File Id  Delete"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/envelopes/{envelope_id}":{"get":{"tags":["signatures"],"summary":"Read Envelope","operationId":"read_envelope_api_v1_sign_envelopes__envelope_id__get","parameters":[{"name":"envelope_id","in":"path","required":true,"schema":{"type":"string","title":"Envelope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Read Envelope Api V1 Sign Envelopes  Envelope Id  Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/envelopes/{envelope_id}/send":{"post":{"tags":["signatures"],"summary":"Send Envelope","description":"Issue the links and notify. **This is the billable moment.**\n\nWhich makes it the one in this file that most wants an\n`Idempotency-Key`: a retry after a timeout charges again *and* emails\nevery signer a second time, so the cost lands on the customer's\ninvoice and on their counterparty's patience at once.\n\nThe envelope's own state is a second guard — `send` on an already-sent\nenvelope is refused — but that refusal is an error, and a caller\nretrying a request it never got an answer to deserves the answer rather\nthan a complaint.","operationId":"send_envelope_api_v1_sign_envelopes__envelope_id__send_post","parameters":[{"name":"envelope_id","in":"path","required":true,"schema":{"type":"string","title":"Envelope Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Send Envelope Api V1 Sign Envelopes  Envelope Id  Send Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/envelopes/{envelope_id}/recipients/{recipient_id}/resend":{"post":{"tags":["signatures"],"summary":"Resend To Recipient","description":"Reissue one signer's link. The previous one dies immediately.\n\nNot a new charge: the envelope was already billed at `send`, and a resend\nis the tenant helping a signer who lost or never received a mail, not a\nsecond signature being requested.\n\nIt still costs, though — an **SMS** does, at two credits, and a signer\nwho gets the same link twice thirty seconds apart is being confused for\nfree. So the key is honoured here too, on the argument that \"not a new\ncharge\" is about the signature and never was about the message.","operationId":"resend_to_recipient_api_v1_sign_envelopes__envelope_id__recipients__recipient_id__resend_post","parameters":[{"name":"envelope_id","in":"path","required":true,"schema":{"type":"string","title":"Envelope Id"}},{"name":"recipient_id","in":"path","required":true,"schema":{"type":"string","title":"Recipient Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Resend To Recipient Api V1 Sign Envelopes  Envelope Id  Recipients  Recipient Id  Resend Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/envelopes/{envelope_id}/recipients/{recipient_id}/replace":{"post":{"tags":["signatures"],"summary":"Replace Recipient","description":"Put somebody else in a signer's place (wrong person, or no longer available).\n\nThe signer's fields and place in the signing order go to the new person, who is invited\nwhen it is their turn; the old link dies and its holder is told it was withdrawn. A\nsigner who confirms with a code by SMS needs the new person's `phone`. A signature already\ngiven, a refusal and a signer skipped by an OR group are never undone. On a `draft` nothing\nhas been sent, so the signer's name, address (and phone) are simply corrected: no mail,\nno callback, one event and one audit row. Charges nothing. The key is honoured because\nthe message the new signer receives has a cost on SMS and a retried request must not\ninvite them twice.","operationId":"replace_recipient_api_v1_sign_envelopes__envelope_id__recipients__recipient_id__replace_post","parameters":[{"name":"envelope_id","in":"path","required":true,"schema":{"type":"string","title":"Envelope Id"}},{"name":"recipient_id","in":"path","required":true,"schema":{"type":"string","title":"Recipient Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReplaceRecipientRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Replace Recipient Api V1 Sign Envelopes  Envelope Id  Recipients  Recipient Id  Replace Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/envelopes/{envelope_id}/cancel":{"post":{"tags":["signatures"],"summary":"Cancel Envelope","description":"Stop an envelope. Charges nothing. The signature is not given back (the work of\nsending was done); the seal and the timestamp it paid at the send are, in this same\ncall, to the credit they came from (`composer.refunds`).\n\nIdempotent through the key as well as by nature. Cancelling twice is\nalready harmless, but the *second* answer is a refusal — the envelope is\nno longer cancellable — and a caller retrying a request it never got an\nanswer to would read that refusal as \"the cancel did not happen\". Which\nis exactly backwards, and exactly the kind of thing somebody acts on.","operationId":"cancel_envelope_api_v1_sign_envelopes__envelope_id__cancel_post","parameters":[{"name":"envelope_id","in":"path","required":true,"schema":{"type":"string","title":"Envelope Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DeclineRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Cancel Envelope Api V1 Sign Envelopes  Envelope Id  Cancel Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/envelopes/{envelope_id}/document":{"get":{"tags":["signatures"],"summary":"Download Signed","description":"The signed PDF: the document, the marks, and the certificate appended.\n\nAnswers the same identifying headers as Composer's own download, so an\narchived file can be traced back to what produced it.","operationId":"download_signed_api_v1_sign_envelopes__envelope_id__document_get","parameters":[{"name":"envelope_id","in":"path","required":true,"schema":{"type":"string","title":"Envelope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/sign/envelopes/{envelope_id}/evidence":{"get":{"tags":["signatures"],"summary":"Download Evidence","description":"Everything needed to defend this signature outside this system, as one\nZIP: the sealed PDF, the source document, and the full event trail as\nstructured data — a superset of what `certificate.py` renders into the\nPDF's own trail page.\n\nAvailable for any *closed* envelope, proving a decline is evidence too.\nA file already gone to retention (Composer's 365-day sweep for the\nsource, Signer's 10-year sweep for the sealed copy and the raw events) is\nsilently omitted rather than failing the whole export — the surviving\nskeleton fields still answer what closed and when.","operationId":"download_evidence_api_v1_sign_envelopes__envelope_id__evidence_get","parameters":[{"name":"envelope_id","in":"path","required":true,"schema":{"type":"string","title":"Envelope Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["signatures:ses"]}],"x-required-scope":"signatures:ses"}},"/api/v1/flow":{"post":{"tags":["flow"],"summary":"Start Flow","description":"Compose the document and put it out for signature, in one call.\n\nAnswers **201** for a flow that was run, **200** for one an\n`Idempotency-Key` matched. Sending that header is optional and strongly\nadvised: this call charges twice and emails real people, so a client that\nretries a timed-out request without one does all of it again.\n\nThe document exists by the time this returns — generation is synchronous,\nbecause it takes well under a second and a link that is not yet a file\nwould make the caller poll for something it could simply have been given.\nWhat takes time is the signature, and nothing here waits for it.\n\n**A key is claimed before any work**, not only recorded on the row at\nthe end — see `composer.idempotency`, \"How the flow uses it\". A retry\nthat arrives while the first attempt is still composing is told\n`IDEMPOTENCY_IN_PROGRESS` (retryable, with `Retry-After`) instead of\nrunning a second composition, a second envelope and a second invitation\nbeside it.","operationId":"start_flow_api_v1_flow_post","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Idempotency-Key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FlowRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Start Flow Api V1 Flow Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["flow:*"]}],"x-required-scope":"flow:*"},"get":{"tags":["flow"],"summary":"List Flows","operationId":"list_flows_api_v1_flow_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","description":"`all`, `production` or `test`; anything else is `all`.","default":"all","title":"Kind"},"description":"`all`, `production` or `test`; anything else is `all`."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Flows Api V1 Flow Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["flow:*"]}],"x-required-scope":"flow:*"}},"/api/v1/flow/{flow_id}":{"get":{"tags":["flow"],"summary":"Read Flow","description":"Where the flow has got to. **This is the authoritative state.**\n\nPoll `output.status` until it stops being `pending`. A callback is the\nother half rather than a replacement — `settings.callbackUrl` has been\ndelivered since 2026-09-17 — and the two are deliberately complementary:\na callback tells you *that* something changed, this says *what is true*.\nA missed delivery therefore never loses state, which is the property that\nmakes an integration safe to build on either one.\n\n`GET /api/v1/flow/{flow_id}/events` answers the third question — **how**\nit got here.","operationId":"read_flow_api_v1_flow__flow_id__get","parameters":[{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","title":"Flow Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Read Flow Api V1 Flow  Flow Id  Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["flow:*"]}],"x-required-scope":"flow:*"}},"/api/v1/flow/{flow_id}/events":{"get":{"tags":["flow"],"summary":"Read Flow Events","description":"The flow's lifecycle in order: composition, then every signature event.\n\nRead-only, and **projected rather than stored** — every line comes off a\nrow that already exists (`generation_job`'s two timestamps,\n`signature_event`'s append-only hash-chained trail). There is no\n`flow_event` table and there should not be one: see\n`orchestrator.timeline`.\n\nWhat it is for: answering \"what actually happened\" without waiting for an\nenvelope to close. The evidence bundle\n(`GET /api/v1/sign/envelopes/{id}/evidence`) is the archival form of the\nsame facts and is available only once the matter is settled, which is the\none moment it is no use for debugging.\n\nAnother organisation's flow answers **404**, like every other id in this\nproduct — the lookup is `flows.get`, tenant-scoped, so this route inherits\nthat rather than restating it.","operationId":"read_flow_events_api_v1_flow__flow_id__events_get","parameters":[{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","title":"Flow Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Read Flow Events Api V1 Flow  Flow Id  Events Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["flow:*"]}],"x-required-scope":"flow:*"}},"/api/v1/flow/{flow_id}/cancel":{"post":{"tags":["flow"],"summary":"Cancel Flow","description":"Stop asking for signatures. Every outstanding link dies immediately.\n\nThe document is untouched and stays fetchable: it exists and was paid for.\nNeither the document nor the signature is refunded — the work was done and the mail went\nout. The envelope's seal and timestamp, paid at the send, are (`composer.refunds`).\n\n**The key here is `Idempotency-Key`, not the flow's own.** `POST /flow`\nis protected by a unique column on `orchestration_flow`, which is a\nguarantee about the resource; a cancel creates no resource, so there is\nnothing for that constraint to be about. Without this, a retried cancel\nanswers with a refusal - the flow is no longer cancellable - and a\ncaller who never saw the first answer reads that as the cancel having\nfailed.","operationId":"cancel_flow_api_v1_flow__flow_id__cancel_post","parameters":[{"name":"flow_id","in":"path","required":true,"schema":{"type":"string","title":"Flow Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DeclineRequest"},{"type":"null"}],"title":"Body"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Cancel Flow Api V1 Flow  Flow Id  Cancel Post"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["flow:*"]}],"x-required-scope":"flow:*"}},"/api/v1/usage":{"get":{"tags":["account"],"summary":"Read Usage","description":"Everything an integration needs to keep itself out of trouble.","operationId":"read_usage_api_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Read Usage Api V1 Usage Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":[]}]}},"/api/v1/callback-environments":{"get":{"tags":["account"],"summary":"List Environments","description":"The organisation's callback environments, the default first.","operationId":"list_environments_api_v1_callback_environments_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response List Environments Api V1 Callback Environments Get"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":[]}]}},"/api/v1/compose/documents/generate":{"post":{"tags":["composer"],"summary":"Generate Document","description":"Render one document and answer with the PDF itself.\n\nThe work moved to `composer.generation.produce` on 2026-09-15 so the\norchestrator could do exactly the same thing without a second copy of it.\nWhat is left here is the part that is genuinely about HTTP: the filename,\nand the headers that let an archived file be traced back to the template\nversion that produced it.","operationId":"generate_document_api_v1_compose_documents_generate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"X-Credits-Used":{"description":"Credits this operation settled (0 for isTest). Never an estimate.","schema":{"type":"integer"}},"X-Credits-Left":{"description":"The account's credits after settlement, queried from the ledger. Not previous balance minus used.","schema":{"type":"integer"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:compose"]}],"x-required-scope":"documents:compose","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]}},"/api/v1/compose/documents/queued/{job_id}":{"get":{"tags":["composer"],"summary":"Get Queued Document","description":"Where a queued document is (`composer.queue`): `queued` (with its `position`), `processing`,\nthen `succeeded` with `documentId` and `downloadUrl`, or `failed` / `expired` / `cancelled` with\nthe `error` (the credit of a document never made is given back). Another organisation's id is\nnot found, like a document's.","operationId":"get_queued_document_api_v1_compose_documents_queued__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:compose"]}],"x-required-scope":"documents:compose"}},"/api/v1/compose/documents/{document_id}":{"get":{"tags":["composer"],"summary":"Get Document","description":"Retrieve a previously generated document.\n\nAuthenticated by API key only. It briefly also required an admin session,\nwhich made the endpoint unusable by the integrations it exists for: every\ncall was answered with a redirect to the login form.","operationId":"get_document_api_v1_compose_documents__document_id__get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:download"]}],"x-required-scope":"documents:download"}},"/api/v1/compose/templates":{"get":{"tags":["composer"],"summary":"List Templates Api","operationId":"list_templates_api_api_v1_compose_templates_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:templates"]}],"x-required-scope":"documents:templates"},"post":{"tags":["composer"],"summary":"Create Template Api","description":"Upload a template. Charges nothing, and creates a row that stays.\n\nWhich is why the key matters here despite the absence of a charge: a\nretried upload leaves a second template with the same name, and the\ncaller then integrates against whichever id came back last while the\nother sits in the console being chosen by somebody in a hurry.","operationId":"create_template_api_api_v1_compose_templates_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:templates"]}],"x-required-scope":"documents:templates","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]}},"/api/v1/compose/templates/{template_id}":{"get":{"tags":["composer"],"summary":"Get Template Api","operationId":"get_template_api_api_v1_compose_templates__template_id__get","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:templates"]}],"x-required-scope":"documents:templates"}},"/api/v1/compose/templates/{template_id}/versions":{"post":{"tags":["composer"],"summary":"Add Template Version Api","description":"Add a version. Same argument as the upload: a retry leaves a spare.","operationId":"add_template_version_api_api_v1_compose_templates__template_id__versions_post","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateVersionCreateRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:templates"]}],"x-required-scope":"documents:templates"}},"/api/v1/compose/templates/{template_id}/versions/{version_number}/activate":{"post":{"tags":["composer"],"summary":"Activate Template Version Api","operationId":"activate_template_version_api_api_v1_compose_templates__template_id__versions__version_number__activate_post","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}},{"name":"version_number","in":"path","required":true,"schema":{"type":"integer","title":"Version Number"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:templates"]}],"x-required-scope":"documents:templates"}},"/api/v1/compose/templates/{template_id}/versions/{version_number}/deactivate":{"post":{"tags":["composer"],"summary":"Deactivate Template Version Api","operationId":"deactivate_template_version_api_api_v1_compose_templates__template_id__versions__version_number__deactivate_post","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}},{"name":"version_number","in":"path","required":true,"schema":{"type":"integer","title":"Version Number"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:templates"]}],"x-required-scope":"documents:templates"}},"/api/v1/compose/templates/{template_id}/deactivate":{"post":{"tags":["composer"],"summary":"Deactivate Template Api","description":"Switch the whole template off, every version with it — same effect as\nthe admin's \"Deactivate\" button, without its confirmation step: a script\ncalling this deliberately meant to do it.","operationId":"deactivate_template_api_api_v1_compose_templates__template_id__deactivate_post","parameters":[{"name":"template_id","in":"path","required":true,"schema":{"type":"string","title":"Template Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:templates"]}],"x-required-scope":"documents:templates"}},"/api/v1/bulk/compose":{"post":{"tags":["bulk"],"summary":"Compose","description":"Submit a batch of documents to compose. Always asynchronous: answers `202`\nwith the job, and the documents are read back as the job progresses.\n\nThe batch is admitted **whole or not at all** — its credit (or its test items)\nis reserved in one step, before any document is rendered, and a batch that\ncannot be paid for or is malformed is refused with nothing left behind. An item\nthat fails is refunded; only a delivered document is charged. Send an\n`Idempotency-Key`: a retried submit then returns the same job.\n\nAlso requires the scope of the single call: `documents:compose`. A token without it is refused with TOKEN_SCOPE_NOT_ALLOWED (403), `details.missingScopes` naming the first scope missing.","operationId":"compose_api_v1_bulk_compose_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkComposeRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"Location":{"description":"The job to poll: /api/v1/bulk/jobs/{jobId}.","schema":{"type":"string"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:submit"]}],"x-required-scope":"bulk:submit","x-also-requires":["documents:compose"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]}},"/api/v1/bulk/files":{"post":{"tags":["bulk"],"summary":"Upload File","description":"Upload a batch — JSONL (one item per line, `{\"externalId\"?, \"data\"}`) or a\nCSV (a header row, one item per row; see the guide for the column mapping) —\nand get a `fileId` to submit with `POST /bulk/compose` or `/bulk/sign`. The\nwhole file is validated before anything is stored: a JSONL is refused whole if\nany line is wrong, a CSV if the file is (a bad CSV *row* becomes a failed item\nthat is never charged). Send the bytes as the raw request body; nothing is\ndecompressed, so a `Content-Encoding` is refused.","operationId":"upload_file_api_v1_bulk_files_post","parameters":[{"name":"format","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"`jsonl` (default) or `csv`; a `text/csv` Content-Type means `csv`.","title":"Format"},"description":"`jsonl` (default) or `csv`; a `text/csv` Content-Type means `csv`."},{"name":"delimiter","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CSV only: `comma`, `semicolon`, `tab` or `pipe`; read from the header when absent.","title":"Delimiter"},"description":"CSV only: `comma`, `semicolon`, `tab` or `pipe`; read from the header when absent."},{"name":"encoding","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"CSV only: `utf-8` (default), `iso-8859-1` or `windows-1252`.","title":"Encoding"},"description":"CSV only: `utf-8` (default), `iso-8859-1` or `windows-1252`."},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:submit"]}],"x-required-scope":"bulk:submit"}},"/api/v1/bulk/jobs":{"get":{"tags":["bulk"],"summary":"List Jobs","description":"The organisation's bulk jobs, newest first.","operationId":"list_jobs_api_v1_bulk_jobs_get","parameters":[{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:read"]}],"x-required-scope":"bulk:read"}},"/api/v1/bulk/jobs/{job_id}":{"get":{"tags":["bulk"],"summary":"Get Job","description":"One job: its state, counts by outcome, credits (`used` is the sum of its\nchildren's, settled; `left` is the ledger now) and, once it is over, the\nreconciliation. Poll this.","operationId":"get_job_api_v1_bulk_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:read"]}],"x-required-scope":"bulk:read"}},"/api/v1/bulk/jobs/{job_id}/items":{"get":{"tags":["bulk"],"summary":"Get Items","description":"Per-item results, in index order, paginated: `after` is the last index you\nhave, `nextAfter` is what to send next (absent on the last page). Each item\nsays whether it succeeded, its document and where to fetch it, or the stable\ncode it failed with — the result manifest of the job.","operationId":"get_items_api_v1_bulk_jobs__job_id__items_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"title":"After"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:read"]}],"x-required-scope":"bulk:read"}},"/api/v1/bulk/jobs/{job_id}/cancel":{"post":{"tags":["bulk"],"summary":"Cancel Job","description":"Stop a job. Items that have not started are cancelled and their credit is\nreleased at once; an item being rendered finishes. Cancelling a job that is\nover changes nothing and answers with it.","operationId":"cancel_job_api_v1_bulk_jobs__job_id__cancel_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:submit"]}],"x-required-scope":"bulk:submit"}},"/api/v1/bulk/jobs/{job_id}/retry":{"post":{"tags":["bulk"],"summary":"Retry Job","description":"Put the **retryable** failed items of a finished job back to work, as new\nattempts under the same job. Each is admitted like a new item (its own\nreservation, the same limits) and an item whose provider request has an\nunknown outcome is never repeated. Answers `202` with the job and `retry`:\nhow many items were put back and which were skipped, with the reason. Nothing\nretryable is `BULK_RETRY_NOT_POSSIBLE`. Claims an `Idempotency-Key`.","operationId":"retry_job_api_v1_bulk_jobs__job_id__retry_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"Location":{"description":"The job to poll: /api/v1/bulk/jobs/{jobId}.","schema":{"type":"string"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:submit"]}],"x-required-scope":"bulk:submit"}},"/api/v1/bulk/jobs/{job_id}/results":{"get":{"tags":["bulk"],"summary":"Get Results","description":"The result bundle: a ZIP with every produced PDF (`documents/<index>.pdf`),\n`manifest.json` (per item: status, sha256, error code and number, credits) and\n`results.csv` (the same, safe to open in a spreadsheet). Only once the job is\nover and while its results are kept (`BULK_RESULTS_UNAVAILABLE` otherwise).\nNeeds `bulk:read` **and** `documents:download`. A job too large for one bundle\nis fetched in ranges with `after` and `limit`.","operationId":"get_results_api_v1_bulk_jobs__job_id__results_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"after","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Only items with an index above this.","title":"After"},"description":"Only items with an index above this."},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":5000,"minimum":1},{"type":"null"}],"description":"At most this many items (a range of a large job).","title":"Limit"},"description":"At most this many items (a range of a large job)."}],"responses":{"200":{"description":"A ZIP: `documents/<index>.pdf` for each produced file, `manifest.json` and `results.csv`.","content":{"application/json":{"schema":{}},"application/zip":{"schema":{"type":"string","format":"binary"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:read"]}],"x-required-scope":"bulk:read"}},"/api/v1/bulk/sign":{"post":{"tags":["bulk"],"summary":"Sign","description":"Submit a batch of envelopes to create **and send**. The same contract as\n`POST /bulk/compose`: asynchronous (`202` and a job), admitted whole or refused\nwhole, one signature reserved per item and charged when it is sent, a failed\nitem refunded, `Idempotency-Key` claimed. Each item is what\n`POST /sign/envelopes?send=true` would do with it - the same validation,\ndefaults, gates, sources, refusals and error codes.\n\nRefused whole, `FEATURE_NOT_AVAILABLE_IN_BULK`: a seal or timestamp (asked for\nor required by the organisation). `FEATURE_NOT_AVAILABLE_IN_TEST_MODE`: a paid\nfeature with `isTest`.\n\nAlso requires the scope of the single call: `signatures:ses`. A token without it is refused with TOKEN_SCOPE_NOT_ALLOWED (403), `details.missingScopes` naming the first scope missing.","operationId":"sign_api_v1_bulk_sign_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkSignRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}},"headers":{"Location":{"description":"The job to poll: /api/v1/bulk/jobs/{jobId}.","schema":{"type":"string"}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:submit"]}],"x-required-scope":"bulk:submit","x-also-requires":["signatures:ses"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]}},"/api/v1/bulk/flow":{"post":{"tags":["bulk"],"summary":"Submit Flow","description":"Submit a batch of **flows**: each item composes a document and puts it out for\nsignature, as `POST /flow` does. The same contract as `POST /bulk/compose` and\n`/bulk/sign`: asynchronous (`202` and a job), admitted whole or refused whole, a\ndocument and a signature reserved per item and each charged when it is delivered, a\nfailed item refunded, `Idempotency-Key` claimed. Each item is what `POST /flow` would\ndo with it - the same validation, defaults, gates, sources, refusals and error codes.\n\nRefused whole, `FEATURE_NOT_AVAILABLE_IN_BULK`: a seal or timestamp (asked for or\nrequired by the organisation). `FEATURE_NOT_AVAILABLE_IN_TEST_MODE`: a paid feature\nwith `isTest`.\n\nAlso requires the scope of the single call: `flow:*`. A token without it is refused with TOKEN_SCOPE_NOT_ALLOWED (403), `details.missingScopes` naming the first scope missing.","operationId":"submit_flow_api_v1_bulk_flow_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkFlowRequest"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["bulk:submit"]}],"x-required-scope":"bulk:submit","x-also-requires":["flow:*"],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]}},"/api/v1/compose/documents/validate":{"post":{"tags":["composer"],"summary":"Validate Document","description":"Everything `generate` would find out, without doing it: diagnostics, missing\nfields, JSON Schema verdict, page count and `estimatedCredits` with its\ncertainty (`exact` or `dependsOn`). **Nothing is charged, reserved or stored.**\nNeeds the same scope as `generate` (`documents:compose`).","operationId":"validate_document_api_v1_compose_documents_validate_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:compose"]}],"x-required-scope":"documents:compose","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]}},"/api/v1/compose/files":{"post":{"tags":["composer"],"summary":"Upload File","description":"Upload an image (PNG, JPEG, WebP) or a PDF once and get a `fileId`.\n\nSend **multipart/form-data** (a `file` part), **JSON** (`{\"fileBase64\",\n\"fileName\"}`) or the **raw bytes** with any other content type\n(`X-File-Name` optional). The type is decided from the bytes. Use the id\nas `{\"$fileId\": \"...\"}` where a payload field needs an image, or in\n`settings.attachments` for a PDF to append. Identical bytes are one file;\nuploading them again returns the same id with `200`.","operationId":"upload_file_api_v1_compose_files_post","responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"requestBody":{"required":true,"description":"The file, three ways: multipart/form-data with a `file` part; JSON `{fileBase64, fileName}`; or the raw bytes (name in `X-File-Name`).","content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}},"application/json":{"schema":{"type":"object","required":["fileBase64"],"properties":{"fileBase64":{"type":"string","format":"byte"},"fileName":{"type":"string"}}}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"security":[{"BearerApiKey":["documents:compose"]}],"x-required-scope":"documents:compose","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}]},"get":{"tags":["composer"],"summary":"List Files","description":"The organisation's live stored files, newest first.","operationId":"list_files_api_v1_compose_files_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:read"]}],"x-required-scope":"documents:read"}},"/api/v1/compose/files/{file_id}":{"get":{"tags":["composer"],"summary":"Get File","description":"One stored file's facts. Another organisation's id is a 404.","operationId":"get_file_api_v1_compose_files__file_id__get","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","title":"File Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:read"]}],"x-required-scope":"documents:read"},"delete":{"tags":["composer"],"summary":"Delete File","description":"Delete a stored file now (the bytes and the id).","operationId":"delete_file_api_v1_compose_files__file_id__delete","parameters":[{"name":"file_id","in":"path","required":true,"schema":{"type":"string","title":"File Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:compose"]}],"x-required-scope":"documents:compose"}},"/api/v1/compose/documents/{document_id}/download-links":{"post":{"tags":["composer"],"summary":"Mint Download Link","description":"Mint a signed address anybody can open until it expires or is revoked: no key,\nno cookie. The `token`/`url` are in this answer **only**: they cannot be read\nagain. Needs `documents:download`.","operationId":"mint_download_link_api_v1_compose_documents__document_id__download_links_post","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/DownloadLinkRequest"},{"type":"null"}],"title":"Req"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:download"]}],"x-required-scope":"documents:download"},"get":{"tags":["composer"],"summary":"List Download Links","description":"The links minted for one document and their state (`active`, `used`,\n`expired`, `revoked`). Tokens are never listed.","operationId":"list_download_links_api_v1_compose_documents__document_id__download_links_get","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:download"]}],"x-required-scope":"documents:download"},"delete":{"tags":["composer"],"summary":"Revoke Document Links","description":"Revoke every live link of one document, at once.","operationId":"revoke_document_links_api_v1_compose_documents__document_id__download_links_delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:download"]}],"x-required-scope":"documents:download"}},"/api/v1/compose/documents/{document_id}/download-links/{link_id}":{"delete":{"tags":["composer"],"summary":"Revoke One Link","description":"Revoke one link. Revoking one that is already revoked is a no-op.","operationId":"revoke_one_link_api_v1_compose_documents__document_id__download_links__link_id__delete","parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string","title":"Document Id"}},{"name":"link_id","in":"path","required":true,"schema":{"type":"string","title":"Link Id"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Makes the call safe to retry: a second request with the same key and the same body gets the first request's answer (24 hours); the same key with a different body is IDEMPOTENCY_KEY_REUSED. Optional, strongly advised.","schema":{"type":"string","maxLength":255}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[{"BearerApiKey":["documents:download"]}],"x-required-scope":"documents:download"}},"/dl/{token}":{"get":{"tags":["download"],"summary":"Download By Link","description":"The document behind a signed download address. **No credential, no cookie.**\n\nOne answer (`404 DOWNLOAD_LINK_INVALID`) for an address that is unknown,\naltered, revoked, already used or no longer matches its document; `410\nDOWNLOAD_LINK_EXPIRED` for a genuine one past its time. Rate limited per\ncaller address. The answer is never cached.","operationId":"download_by_link_dl__token__get","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","title":"Token"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}},"application/pdf":{}}},"422":{"description":"INVALID_REQUEST_BODY (1101): the body does not match the expected shape; details.fields names each field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Any other failure: the same envelope, with a stable `code` and `number` (see the outcomes table in the guide).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}},"security":[]}}},"components":{"schemas":{"ApiError":{"type":"object","description":"The body of every failure: a stable code and number, a message for a developer, never to be pattern-matched.","required":["code","number","message","retryable"],"properties":{"code":{"type":"string","enum":["MISSING_CREDENTIALS","INVALID_API_KEY","IP_NOT_ALLOWED","TENANT_INACTIVE","SUITE_NOT_ENABLED","ADMIN_LOGIN_REQUIRED","FEATURE_NOT_ENABLED","TOKEN_SCOPE_NOT_ALLOWED","FEATURE_NOT_AVAILABLE_IN_TEST_MODE","FEATURE_NOT_AVAILABLE_IN_BULK","REQUIRED_FEATURE_NOT_AVAILABLE_IN_TEST_MODE","TIMESTAMP_REQUIRES_SEAL","INVALID_REQUEST_BODY","INVALID_JSON","DATALESS_NOT_AVAILABLE","IDEMPOTENCY_KEY_REUSED","IDEMPOTENCY_IN_PROGRESS","IDEMPOTENT_RESULT_GONE","BULK_INPUT_INVALID","JSON_STRUCTURE_LIMIT_EXCEEDED","IDEMPOTENCY_KEY_REQUIRED","FILE_REJECTED","TEMPLATE_NOT_FOUND","TEMPLATE_DEACTIVATED","TEMPLATE_VERSION_NOT_FOUND","TEMPLATE_VERSION_NOT_ACTIVE","NO_ACTIVE_VERSION","TEMPLATE_FILE_INVALID","TEMPLATE_FILE_REJECTED","JSON_SCHEMA_INVALID","MISSING_TEMPLATE_FIELD","TEMPLATE_DATA_MISMATCH","PAYLOAD_SCHEMA_VIOLATION","DOCUMENT_NOT_FOUND","BULK_JOB_NOT_FOUND","BULK_FILE_NOT_FOUND","BULK_RESULTS_UNAVAILABLE","BULK_RETRY_NOT_POSSIBLE","STORED_FILE_NOT_FOUND","DOWNLOAD_LINK_NOT_FOUND","DOWNLOAD_LINK_INVALID","DOWNLOAD_LINK_EXPIRED","SIGNATURE_LEVEL_UNAVAILABLE","ENVELOPE_NOT_FOUND","ENVELOPE_NOT_EDITABLE","ENVELOPE_CLOSED","ENVELOPE_NOT_CLOSED","DOCUMENT_NOT_SIGNABLE","DOCUMENT_SOURCE_UNAVAILABLE","SIGNING_LINK_INVALID","SIGNING_LINK_EXPIRED","SIGNING_OUT_OF_TURN","SIGNATURE_TYPE_NOT_ALLOWED","RECIPIENT_ALREADY_SIGNED","DELEGATION_NOT_ALLOWED","OTP_REQUIRED","OTP_INVALID","OTP_TOO_MANY_ATTEMPTS","RECIPIENT_NOT_FOUND","VALIDATION_MODE_UNAVAILABLE","RECIPIENT_NOT_REQUIRED","STORED_FILE_IN_USE","SOURCE_FILE_CHANGED","SIGNER_FIELD_INVALID","CALLBACK_DELIVERY_NOT_FOUND","SMS_VALIDATION_UNAVAILABLE","CALLBACK_ENVIRONMENT_UNKNOWN","CALLBACK_PATH_INVALID","CALLBACK_ENVIRONMENT_IN_USE","CALLBACK_ENVIRONMENT_INVALID","SIGNATURE_TAG_UNKNOWN_SIGNER","SIGNER_NOT_PLACED","FLOW_NOT_FOUND","FLOW_CLOSED","QUOTA_EXCEEDED","RATE_LIMIT_EXCEEDED","PAYLOAD_TOO_LARGE","SERVER_BUSY","SERVICE_PAUSED","RECIPIENT_VOLUME_EXCEEDED","TEST_QUOTA_EXCEEDED","TEST_CAPACITY_TEMPORARILY_LIMITED","QUEUE_CAPACITY_EXCEEDED","TENANT_CONCURRENCY_LIMIT_REACHED","BULK_ITEM_LIMIT_EXCEEDED","JOB_TOO_LARGE","BULK_CONCURRENCY_LIMIT_REACHED","MAINTENANCE_MODE","PURCHASE_AMOUNT_TOO_LARGE","SUBSCRIPTION_ALLOWANCE_EXHAUSTED","FILE_LIMIT_REACHED","RENDERING_FAILED","CONVERSION_FAILED","CONVERSION_TIMEOUT","STORAGE_UNAVAILABLE","INTERNAL_ERROR","TRUST_PROVIDER_NOT_CONFIGURED","TRUST_PROVIDER_UNAVAILABLE","SEAL_FAILED","TIMESTAMP_FAILED","BULK_JOB_TIMED_OUT","PROVIDER_BILLING_PROFILE_INCOMPLETE"]},"number":{"type":"integer","enum":[1001,1002,1003,1004,1005,1006,1007,1008,1009,1010,1011,1012,1101,1102,1103,1104,1105,1106,1107,1108,1109,1121,1201,1202,1203,1204,1205,1301,1302,1303,1401,1402,1403,1501,1502,1503,1504,1505,1520,1521,1522,1523,1601,1602,1603,1604,1605,1606,1607,1608,1609,1610,1611,1612,1613,1614,1615,1616,1617,1618,1619,1620,1621,1622,1623,1624,1625,1626,1627,1628,1629,1630,1701,1702,1801,1802,1803,1804,1805,1806,1807,1808,1809,1810,1811,1812,1813,1814,1815,1816,1830,1901,1902,1903,1904,1905,1906,1907,1908,1909,1910,1911]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true},"retryable":{"type":"boolean"},"requestId":{"type":"string"},"output":{"$ref":"#/components/schemas/Output"}}},"ApiWarning":{"type":"object","description":"One entry of output.warnings: the call succeeded having done less than asked.","required":["code","number","message"],"properties":{"code":{"type":"string","enum":["SEAL_NOT_ENABLED","TIMESTAMP_NOT_ENABLED","SEAL_REQUIRED_BY_ORGANISATION","TIMESTAMP_REQUIRED_BY_ORGANISATION","SEAL_NOT_CONFIGURED","TIMESTAMP_NOT_CONFIGURED","SEAL_NOT_APPLIED","TIMESTAMP_NOT_APPLIED","SEAL_NOT_ENTITLED","TIMESTAMP_NOT_ENTITLED","PAID_EXTRA_SKIPPED_ON_TEST","DELEGATION_NOT_ENABLED","DELEGATION_REQUIRED_BY_ORGANISATION","TEMPLATE_FIELDS_MISSING","RENDER_NOTES","PAYLOAD_SCHEMA_VIOLATIONS","TRUST_NOT_QUALIFIED","COMPRESSION_SKIPPED","PDFA_NOT_VERIFIED","ATTESTATION_REFUNDED_ENVELOPE_CLOSED","ATTESTATION_REFUNDED_NOT_APPLIED","ATTESTATION_REFUNDED_OUTCOME_UNKNOWN","DOCUMENT_NOT_STORED","DOCUMENT_STORED_FOR_SIGNATURE","DOCUMENT_STORED_FOR_BULK"]},"number":{"type":"integer","enum":[2001,2002,2003,2004,2005,2006,2007,2008,2009,2010,2101,2102,2103,2104,2105,2106,2107,2120,2121,2130,2131,2132,2201,2202,2203]},"message":{"type":"string"},"details":{"type":"object","additionalProperties":true}}},"BulkCallbackUrls":{"properties":{"env":{"anyOf":[{"type":"string","maxLength":16,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,15}$"},{"type":"null"}],"title":"Env"},"onSuccess":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Onsuccess"},"onError":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Onerror"}},"additionalProperties":false,"type":"object","title":"BulkCallbackUrls","description":"The **completion webhook** of a job: `onSuccess` is called when every item\ndelivered, `onError` for every other end (partial, failed, cancelled). Same\nshape, same signature (`X-Signer-Signature`, HMAC-SHA256 of the raw body under\nthe organisation's callback secret), same retries and the same SSRF guard as\nan envelope's `callbackUrl` - it is delivered by the same code. https only,\nor (2026-10-19) a callback environment: `env` and paths, exactly as an\nenvelope's (`composer.callback_environments`), validated at submission."},"BulkComposeRequest":{"properties":{"settings":{"$ref":"#/components/schemas/GenerationSettings"},"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/BulkItemIn"},"type":"array"},{"type":"null"}],"title":"Items"},"fileId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fileid"},"options":{"anyOf":[{"$ref":"#/components/schemas/BulkOptions"},{"type":"null"}]},"callbackUrl":{"anyOf":[{"$ref":"#/components/schemas/BulkCallbackUrls"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["settings"],"title":"BulkComposeRequest","description":"`POST /api/v1/bulk/compose`. Exactly one of `items` and `fileId`.\n\n`settings` is the same object a single compose call takes, applied to every\nitem, with these exceptions (refused whole, `FEATURE_NOT_AVAILABLE_IN_BULK`):\n`qeSeal`, `qualifiedTimestamp`, `password`, `responseFormat` other than\n`pdf`, and `filename`."},"BulkFlowItemIn":{"properties":{"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Externalid"},"data":{"additionalProperties":true,"type":"object","title":"Data"},"signers":{"additionalProperties":{"$ref":"#/components/schemas/RecipientRequest"},"type":"object","title":"Signers"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentRef"},"type":"array"},{"type":"null"}],"title":"Documents"}},"additionalProperties":false,"type":"object","required":["signers"],"title":"BulkFlowItemIn","description":"One flow of a batch: the `data` of the template and the `signers` of the\nenvelope, exactly as `POST /flow` takes them. `subject`, `message` and `documents`\n(annexes) are optional per-item settings laid over the shared `signature`."},"BulkFlowRequest":{"properties":{"settings":{"$ref":"#/components/schemas/GenerationSettings"},"signature":{"$ref":"#/components/schemas/BulkFlowSignature"},"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/BulkFlowItemIn"},"type":"array"},{"type":"null"}],"title":"Items"},"fileId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fileid"},"options":{"anyOf":[{"$ref":"#/components/schemas/BulkOptions"},{"type":"null"}]},"callbackUrl":{"anyOf":[{"$ref":"#/components/schemas/BulkCallbackUrls"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["settings"],"title":"BulkFlowRequest","description":"`POST /api/v1/bulk/flow`. Exactly one of `items` and `fileId` (a JSONL or CSV\nupload whose rows are `{data, signers, ...}`).\n\n`settings` is the composition half of `POST /flow` (`templateId`, `isTest`, ...),\napplied to every item; `signature` is the shared half of its signature block.\nRefused whole, `FEATURE_NOT_AVAILABLE_IN_BULK`: a seal or a timestamp."},"BulkFlowSignature":{"properties":{"level":{"type":"string","enum":["SES","AES","QES"],"title":"Level","description":"Signature level. Only `SES` is produced today. `AES` and `QES` are coming soon (next wave): accepted by the contract, refused with `SIGNATURE_LEVEL_UNAVAILABLE` (1601), never served as SES.","default":"SES"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"}},"additionalProperties":true,"type":"object","title":"BulkFlowSignature","description":"The **shared** part of a flow's `signature` block (everything but `signers`,\nwhich each item brings). Open on purpose, like the signing batch's settings: any\nother key of the block (`language`, `reminderFrequencyHours`, `callbackUrl`, ...) is\naccepted here and validated, with each item, by the very model `POST /flow` uses.\nThe few that are named are the ones the platform's own sweeps need to *see*."},"BulkItemIn":{"properties":{"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Externalid"},"data":{"additionalProperties":true,"type":"object","title":"Data"}},"additionalProperties":false,"type":"object","required":["data"],"title":"BulkItemIn","description":"One document of an inline batch. `data` is what a single compose call sends\nas `data`; `externalId` is the caller's own reference for the item (optional,\nunique in the batch)."},"BulkOptions":{"properties":{"maxItems":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Maxitems"}},"additionalProperties":false,"type":"object","title":"BulkOptions","description":"Per-request limits the caller may set **lower** than the platform's, never\nhigher (v9 §13: `min(requested, tenant, platform)`)."},"BulkSignItemIn":{"properties":{"externalId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Externalid"},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentRef"},"type":"array"},{"type":"null"}],"title":"Documents"},"documentId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Documentid"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"signers":{"additionalProperties":{"$ref":"#/components/schemas/RecipientRequest"},"type":"object","title":"Signers"}},"additionalProperties":false,"type":"object","required":["signers"],"title":"BulkSignItemIn","description":"One envelope of a signing batch. `signers` is `POST /sign/envelopes`'s\n`signers`, unchanged; the rest are optional per-item settings (see the module\ndocstring). `externalId` is the caller's own reference for the item."},"BulkSignRequest":{"properties":{"settings":{"$ref":"#/components/schemas/BulkSignSettings"},"items":{"anyOf":[{"items":{"$ref":"#/components/schemas/BulkSignItemIn"},"type":"array"},{"type":"null"}],"title":"Items"},"fileId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Fileid"},"options":{"anyOf":[{"$ref":"#/components/schemas/BulkOptions"},{"type":"null"}]},"callbackUrl":{"anyOf":[{"$ref":"#/components/schemas/BulkCallbackUrls"},{"type":"null"}]}},"additionalProperties":false,"type":"object","required":["settings"],"title":"BulkSignRequest","description":"`POST /api/v1/bulk/sign`. Exactly one of `items` and `fileId` (a JSONL or CSV\nupload whose rows are `{signers, documents?, ...}`).\n\n`settings` is the **shared** part of an envelope's `settings` (an object, so\nthat the documents may be shared or per item); each item is validated, merged\nwith it, as the `EnvelopeCreateRequest` a single call takes."},"BulkSignSettings":{"properties":{"isTest":{"type":"boolean","title":"Istest","default":false},"level":{"type":"string","enum":["SES","AES","QES"],"title":"Level","description":"Signature level. Only `SES` is produced today. `AES` and `QES` are coming soon (next wave): accepted by the contract, refused with `SIGNATURE_LEVEL_UNAVAILABLE` (1601), never served as SES.","default":"SES"},"subject":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subject"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentRef"},"type":"array"},{"type":"null"}],"title":"Documents"},"documentId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Documentid"}},"additionalProperties":true,"type":"object","title":"BulkSignSettings","description":"The **shared** part of an envelope's `settings` (see `POST /sign/envelopes`).\n\nOpen on purpose: any other key of an envelope's `settings` (`language`,\n`hasSigningOrder`, `reminderFrequencyHours`, `callbackUrl`, `cc`, ...) is\naccepted here and validated, with each item, by the very model a single call\nuses. The few that are named are the ones a caller and the platform's own\nsweeps need to *see* in the contract - above all `isTest`, so that every door\nthat accepts it is found from the OpenAPI document\n(`test_istest_never_pays.py`)."},"CallbackUrls":{"properties":{"env":{"anyOf":[{"type":"string","maxLength":16,"minLength":1,"pattern":"^[a-z][a-z0-9_]{0,15}$"},{"type":"null"}],"title":"Env","description":"The sigla of one of the organisation's callback environments (the console's Callback environments page). With it, `onSuccess` and `onError` are paths appended to the environment's base URL."},"onSuccess":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Onsuccess"},"onError":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Onerror"},"onEvent":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Onevent","description":"Optional. Where a **non-terminal** event is POSTed: today `recipient.replaced`, when a signer is replaced. A full https URL, or a path with `env`. Never `onSuccess` or `onError`, which only ever hear how the envelope ended."}},"additionalProperties":false,"type":"object","title":"CallbackUrls","description":"Where the envelope's outcome is POSTed (`signer.callbacks`).\n\nEither two full https URLs (no authentication but our HMAC), or a **callback\nenvironment** (2026-10-19): `env` names one of the organisation's environments\nand `onSuccess` / `onError` are paths appended to its base URL, sent with its\nauthentication. Without `env`, paths go to the default environment."},"DeclineRequest":{"properties":{"reason":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Reason"}},"additionalProperties":false,"type":"object","title":"DeclineRequest"},"DocumentRef":{"properties":{"documentId":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Documentid"},"fileId":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Fileid"},"sha256":{"anyOf":[{"type":"string","maxLength":64,"minLength":64,"pattern":"^[0-9a-fA-F]{64}$"},{"type":"null"}],"title":"Sha256"},"fileBase64":{"anyOf":[{"type":"string","minLength":1},{"type":"null"}],"title":"Filebase64"},"fileName":{"anyOf":[{"type":"string","maxLength":255,"minLength":1},{"type":"null"}],"title":"Filename"},"signatureTags":{"type":"boolean","title":"Signaturetags","default":false}},"additionalProperties":false,"type":"object","title":"DocumentRef","description":"One source document of an envelope: ours, or the customer's own PDF.\n\nExactly one of three, and all three are performed (2026-10-04; until then\nthe last two were refused, `DOCUMENT_SOURCE_UNAVAILABLE`):\n\n**`documentId`**: something this service produced (Composer Fly, or the\ndocument of a flow). The chain from data to document to signature is what a\nseal attests.\n\n**`fileId`**: a PDF the customer uploaded once (`POST /api/v1/sign/files`)\nand may use for any number of envelopes. Referenced, not copied; the\nenvelope pins its hash. `sha256` may be added to be refused\n(`SOURCE_FILE_CHANGED`) if the id does not name the bytes the caller means.\n\n**`fileBase64`** (+ `fileName`): the one-shot form - the same upload, inline,\nthrough the same validation and storage, answering no `fileId` but leaving\none on the account (it is the same file; list it, reuse it, delete it).\nAn uploaded file has no provenance to certify, and the certificate of\ncompletion says so: it lists such a source as *uploaded by the customer*."},"DownloadLinkRequest":{"properties":{"expiresInSeconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Expiresinseconds"},"singleUse":{"type":"boolean","title":"Singleuse","default":false}},"additionalProperties":false,"type":"object","title":"DownloadLinkRequest"},"EnvelopeCreateRequest":{"properties":{"signers":{"additionalProperties":{"$ref":"#/components/schemas/RecipientRequest"},"type":"object","minProperties":1,"title":"Signers"},"settings":{"$ref":"#/components/schemas/EnvelopeSettings"}},"additionalProperties":false,"type":"object","required":["signers","settings"],"title":"EnvelopeCreateRequest"},"EnvelopeSettings":{"properties":{"documentId":{"anyOf":[{"type":"string","maxLength":64,"minLength":1},{"type":"null"}],"title":"Documentid"},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentRef"},"type":"array","maxItems":10},{"type":"null"}],"title":"Documents"},"isTest":{"type":"boolean","title":"Istest","default":false},"level":{"type":"string","enum":["SES","AES","QES"],"title":"Level","description":"Signature level. Only `SES` is produced today. `AES` and `QES` are coming soon (next wave): accepted by the contract, refused with `SIGNATURE_LEVEL_UNAVAILABLE` (1601), never served as SES.","default":"SES"},"subject":{"type":"string","maxLength":200,"title":"Subject","default":""},"message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Message"},"hasSigningOrder":{"type":"boolean","title":"Hassigningorder","default":false},"expirationDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expirationdate"},"reminderFrequencyHours":{"type":"integer","maximum":720.0,"minimum":0.0,"title":"Reminderfrequencyhours","default":0},"cc":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Cc"},"ccNotifyOn":{"type":"string","enum":["none","completion","everything"],"title":"Ccnotifyon","default":"none"},"bcc":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Bcc"},"bccNotifyOn":{"type":"string","enum":["none","completion","everything"],"title":"Bccnotifyon","default":"none"},"language":{"type":"string","enum":["en","it"],"title":"Language","default":"en"},"callbackUrl":{"$ref":"#/components/schemas/CallbackUrls"},"seal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Seal"},"timestamp":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Timestamp"},"allowDelegation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Allowdelegation"}},"additionalProperties":false,"type":"object","title":"EnvelopeSettings"},"FieldPlacement":{"properties":{"kind":{"type":"string","enum":["signature","name","date","text","checkbox","dropdown"],"title":"Kind","default":"signature"},"document":{"type":"integer","maximum":10.0,"minimum":1.0,"title":"Document","default":1},"page":{"type":"integer","maximum":2000.0,"minimum":1.0,"title":"Page","default":1},"x":{"type":"number","maximum":1.0,"minimum":0.0,"title":"X"},"y":{"type":"number","maximum":1.0,"minimum":0.0,"title":"Y"},"width":{"type":"number","maximum":1.0,"exclusiveMinimum":0.0,"title":"Width","default":0.25},"height":{"type":"number","maximum":1.0,"exclusiveMinimum":0.0,"title":"Height","default":0.06},"label":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"Label"},"required":{"type":"boolean","title":"Required","default":true},"options":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Options"},"value":{"anyOf":[{"type":"string"},{"type":"boolean"},{"type":"null"}],"title":"Value"},"locked":{"type":"boolean","title":"Locked","default":false}},"additionalProperties":false,"type":"object","required":["x","y"],"title":"FieldPlacement","description":"Where one mark or input goes, in fractions of the page box.\n\nFractions rather than points so the placement survives the document being\nre-rendered at another page size. Origin is top-left — how a person\ndescribes a page — and the conversion to the PDF's bottom-left origin\nhappens once, in `signer.marks`.\n\n**Inputs** (`text`, `checkbox`, `dropdown`): `label` is the question the\nsigner sees; `required` (default true) means the signature is refused until\nit is answered (a required checkbox must be ticked); `value` is what the\nsender prefilled, which the signer may change unless `locked`; a dropdown\nhas `options`. None of these means anything on a `signature`, `name` or\n`date`, and a request that sets one there is refused, never ignored."},"FlowRequest":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"},"settings":{"$ref":"#/components/schemas/GenerationSettings"},"signature":{"$ref":"#/components/schemas/SignatureBlock"}},"additionalProperties":false,"type":"object","required":["settings","signature"],"title":"FlowRequest","description":"`data` + `settings` + `signature`, and nothing else."},"GenerateRequest":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"},"settings":{"$ref":"#/components/schemas/GenerationSettings"}},"additionalProperties":false,"type":"object","required":["data","settings"],"title":"GenerateRequest"},"GenerationSettings":{"properties":{"templateId":{"type":"string","title":"Templateid"},"templateVersion":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Templateversion"},"pdfA":{"type":"string","enum":["none","1b","2b","3b"],"title":"Pdfa","default":"none"},"colorMode":{"type":"string","enum":["color","gray","blackwhite"],"title":"Colormode","default":"color"},"compressionLevel":{"type":"string","enum":["none","lossless","balanced","small"],"title":"Compressionlevel","default":"none"},"attachments":{"items":{"type":"string"},"type":"array","maxItems":5,"title":"Attachments"},"password":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Password"},"pdfUA":{"type":"boolean","title":"Pdfua","default":false},"filename":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Filename"},"metadata":{"items":{"$ref":"#/components/schemas/MetadataTag"},"type":"array","title":"Metadata"},"watermark":{"$ref":"#/components/schemas/Watermark"},"locale":{"type":"string","const":"it-IT","title":"Locale","default":"it-IT"},"dataless":{"type":"boolean","title":"Dataless","default":false},"isTest":{"type":"boolean","title":"Istest","default":false},"responseFormat":{"type":"string","enum":["pdf","json"],"title":"Responseformat","default":"pdf"},"queueIfBusy":{"type":"boolean","title":"Queueifbusy","default":false},"qeSeal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Qeseal","description":"Apply DoConure's qualified electronic seal (2 credits; 6 with `qualifiedTimestamp`): it attests the file's origin and integrity, not who signed. Refused with `FEATURE_NOT_ENABLED` when the organisation does not hold it and with `TRUST_PROVIDER_NOT_CONFIGURED` when the platform does not offer it; omit it to follow the organisation's setting."},"qualifiedTimestamp":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Qualifiedtimestamp","description":"A qualified timestamp inside the seal (PAdES B-LT), only ever together with `qeSeal` (`TIMESTAMP_REQUIRES_SEAL` otherwise). Costs 4 credits more than the seal alone."}},"additionalProperties":false,"type":"object","required":["templateId"],"title":"GenerationSettings","description":"Everything about a generation request that is not template data.\n\n`templateId`/`templateVersion` live here rather than at the request root:\n`data` is the only thing the template reads, everything else — which\ntemplate, and how the PDF is produced — is a setting."},"MetadataTag":{"properties":{"name":{"type":"string","title":"Name"},"value":{"type":"string","title":"Value"}},"additionalProperties":false,"type":"object","required":["name","value"],"title":"MetadataTag","description":"One PDF Info-dictionary entry. A list rather than fixed `title`/`author`\nfields, so a caller can set the well-known ones or a custom key without a\nschema change — see composer/postprocess.py for the name -> PDF key map."},"Output":{"type":"object","description":"The one object every JSON answer carries: one section per URL prefix.","required":["status","compose","sign","flow","credits","warnings","error"],"properties":{"status":{"type":"string","enum":["succeeded","pending","failed"]},"input":{"type":["object","null"]},"compose":{"type":["object","null"]},"sign":{"type":["object","null"]},"flow":{"type":["object","null"]},"bulk":{"type":["object","null"],"description":"Present only on /api/v1/bulk answers."},"credits":{"type":["object","null"],"properties":{"items":{"type":"array","items":{"type":"object","required":["unit","quantity","credits","paidBy"],"properties":{"unit":{"type":"string","enum":["document","signature","sms","seal","timestamp"]},"quantity":{"type":"integer"},"credits":{"type":"integer"},"paidBy":{"type":"string","enum":["credit","plan"]}}}},"used":{"type":"integer"},"left":{"type":"integer"},"testRemaining":{"type":"integer"}}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/ApiWarning"}},"error":{"anyOf":[{"$ref":"#/components/schemas/ApiError"},{"type":"null"}]}}},"RecipientRequest":{"properties":{"email":{"type":"string","maxLength":320,"minLength":3,"title":"Email"},"fullName":{"type":"string","maxLength":200,"minLength":1,"title":"Fullname"},"fields":{"items":{"$ref":"#/components/schemas/FieldPlacement"},"type":"array","title":"Fields"},"order":{"anyOf":[{"type":"integer","maximum":1000.0,"minimum":1.0},{"type":"null"}],"title":"Order"},"groupMode":{"anyOf":[{"type":"string","enum":["AND","OR"]},{"type":"null"}],"title":"Groupmode"},"validationMode":{"type":"string","enum":["sign","email","sms"],"title":"Validationmode","default":"sign"},"signatureMeaning":{"anyOf":[{"type":"string","enum":["approved","reviewed","authored","verified","responsibility_accepted"]},{"type":"null"}],"title":"Signaturemeaning"},"phone":{"anyOf":[{"type":"string","maxLength":32,"minLength":3},{"type":"null"}],"title":"Phone"}},"additionalProperties":false,"type":"object","required":["email","fullName"],"title":"RecipientRequest"},"ReplaceRecipientRequest":{"properties":{"email":{"type":"string","maxLength":320,"minLength":3,"title":"Email"},"fullName":{"type":"string","maxLength":200,"minLength":1,"title":"Fullname"},"reason":{"anyOf":[{"type":"string","maxLength":500},{"type":"null"}],"title":"Reason"},"phone":{"anyOf":[{"type":"string","maxLength":32,"minLength":3},{"type":"null"}],"title":"Phone"}},"additionalProperties":false,"type":"object","required":["email","fullName"],"title":"ReplaceRecipientRequest","description":"`POST .../recipients/{id}/replace` (1.2): the sender puts somebody else in a signer's place.\n\nThe same checks run again in `envelopes.replace_recipient`, which the console form reaches\nwithout this schema: one rule for both doors."},"SignatureBlock":{"properties":{"documentId":{"type":"null","title":"Documentid"},"documents":{"anyOf":[{"items":{"$ref":"#/components/schemas/DocumentRef"},"type":"array","maxItems":9},{"type":"null"}],"title":"Documents"},"isTest":{"type":"null","title":"Istest"},"level":{"type":"string","enum":["SES","AES","QES"],"title":"Level","description":"Signature level. Only `SES` is produced today. `AES` and `QES` are coming soon (next wave): accepted by the contract, refused with `SIGNATURE_LEVEL_UNAVAILABLE` (1601), never served as SES.","default":"SES"},"subject":{"type":"string","maxLength":200,"title":"Subject","default":""},"message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"title":"Message"},"hasSigningOrder":{"type":"boolean","title":"Hassigningorder","default":false},"expirationDate":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expirationdate"},"reminderFrequencyHours":{"type":"integer","maximum":720.0,"minimum":0.0,"title":"Reminderfrequencyhours","default":0},"cc":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Cc"},"ccNotifyOn":{"type":"string","enum":["none","completion","everything"],"title":"Ccnotifyon","default":"none"},"bcc":{"items":{"type":"string"},"type":"array","maxItems":20,"title":"Bcc"},"bccNotifyOn":{"type":"string","enum":["none","completion","everything"],"title":"Bccnotifyon","default":"none"},"language":{"type":"string","enum":["en","it"],"title":"Language","default":"en"},"callbackUrl":{"$ref":"#/components/schemas/CallbackUrls"},"seal":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Seal"},"timestamp":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Timestamp"},"allowDelegation":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Allowdelegation"},"signers":{"additionalProperties":{"$ref":"#/components/schemas/RecipientRequest"},"type":"object","minProperties":1,"title":"Signers"}},"additionalProperties":false,"type":"object","required":["signers"],"title":"SignatureBlock","description":"Signer's half: every field `EnvelopeSettings` has, minus `documentId` —\nthe document does not exist yet when this is written, which is the whole\npoint of the flow. `orchestrator.flows.start` fills `documentId` in once\nComposer has produced one, and hands the rest through unchanged.\n\nSubclassing rather than duplicating the field list is what keeps the two\ncontracts from drifting: a new envelope setting is a flow setting too the\nmoment it is added to `EnvelopeSettings`, with no second place to remember."},"SourceFileRequest":{"properties":{"fileName":{"type":"string","maxLength":255,"minLength":1,"title":"Filename"},"fileBase64":{"type":"string","minLength":1,"title":"Filebase64"}},"additionalProperties":false,"type":"object","required":["fileName","fileBase64"],"title":"SourceFileRequest","description":"`POST /api/v1/sign/files`: upload a PDF once, get a `fileId`.\n\nInline base64, like every other upload in this API (`POST /templates`), so\none HTTP client and one Idempotency-Key story cover them all. A new\nversion of a file is simply a new upload and a new `fileId`: a file never\nchanges, and the old one keeps working for every envelope that uses it."},"TemplateCreateRequest":{"properties":{"name":{"type":"string","maxLength":200,"minLength":1,"title":"Name"},"templateType":{"type":"string","enum":["docx","html","xlsx"],"title":"Templatetype"},"fileBase64":{"type":"string","minLength":1,"title":"Filebase64"},"fileName":{"type":"string","maxLength":255,"minLength":1,"title":"Filename"},"jsonSchema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Jsonschema"},"errorOnMissingFields":{"type":"boolean","title":"Erroronmissingfields","default":false},"payloadValidation":{"type":"string","enum":["off","warn","reject"],"title":"Payloadvalidation","default":"warn"}},"additionalProperties":false,"type":"object","required":["name","templateType","fileBase64","fileName"],"title":"TemplateCreateRequest","description":"`POST /api/v1/compose/templates` — the file travels as base64 inside the JSON\nbody, like everything else in this API, rather than multipart: it keeps\nevery endpoint the same shape for callers (Salesforce Apex in particular\nhas no pleasant multipart story) and reuses the same error envelope for a\nbad request instead of a second parsing path."},"TemplateVersionCreateRequest":{"properties":{"fileBase64":{"type":"string","minLength":1,"title":"Filebase64"},"fileName":{"type":"string","maxLength":255,"minLength":1,"title":"Filename"},"jsonSchema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Jsonschema"},"payloadValidation":{"anyOf":[{"type":"string","enum":["off","warn","reject"]},{"type":"null"}],"title":"Payloadvalidation"}},"additionalProperties":false,"type":"object","required":["fileBase64","fileName"],"title":"TemplateVersionCreateRequest","description":"`POST /api/v1/compose/templates/{templateId}/versions` — a new version always\narrives inactive, same as an admin upload: uploading is not publishing."},"ValidateRequest":{"properties":{"data":{"additionalProperties":true,"type":"object","title":"Data"},"settings":{"$ref":"#/components/schemas/GenerationSettings"},"estimatePages":{"type":"boolean","title":"Estimatepages","default":true},"plannedExtras":{"items":{"type":"string","const":"signature"},"type":"array","title":"Plannedextras","default":[]}},"additionalProperties":false,"type":"object","required":["data","settings"],"title":"ValidateRequest","description":"`POST /documents/validate`: the body of `generate`, plus two dry-run options."},"Watermark":{"properties":{"enable":{"type":"string","enum":["off","on"],"title":"Enable","default":"off"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"}},"additionalProperties":false,"type":"object","title":"Watermark"}},"securitySchemes":{"BearerApiKey":{"type":"http","scheme":"bearer","description":"An organisation API key, `Authorization: Bearer lpdc_...`. Each operation lists the token scope it needs."}}}}