{"openapi":"3.1.0","info":{"title":"squiggli API","version":"1.0.0","description":"Send documents for e-signature with one call. Agent guide: /llms.txt. Errors: { error: { code, message } } with a message that says how to fix it."},"servers":[{"url":"https://squiggli.billy-965.workers.dev/v1"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"sq_live_... or sq_test_... (test keys only make test envelopes)"},"platform":{"type":"http","scheme":"bearer","description":"Chesterman's apps (Kiewa Trades, Patch, Kiewa): sqp_..., with the Kiewa business id in the path"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"add_card_url":{"type":"string"}},"required":["code","message"]}}},"CreateEnvelope":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200,"description":"What signers see, e.g. \"Harbour Lane lease, unit 4\"."},"message":{"description":"A note to signers, shown in the email and on the signing page.","type":"string","maxLength":2000},"documents":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"object","properties":{"name":{"description":"File name shown to signers. Defaults to the template name or \"Document 1\".","type":"string","minLength":1,"maxLength":200},"file_base64":{"description":"A PDF, base64-encoded. Up to 10 MB.","type":"string","maxLength":14000000},"file_url":{"description":"An https link squiggli downloads the PDF from (up to 10 MB).","type":"string","format":"uri"},"template_id":{"description":"Render this template (tpl_...) as the document.","type":"string"},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},"description":"Values for the template's {{variables}}, e.g. {\"client.name\": \"Ava Chen\", \"rent\": \"$650 a week\"}."}},"description":"One document in the envelope: a PDF (file_base64 or file_url) or a template (template_id + variables)."}},"template_id":{"description":"Shortcut for documents: [{ template_id, variables }].","type":"string"},"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},"description":"Values for the template's {{variables}}, e.g. {\"client.name\": \"Ava Chen\", \"rent\": \"$650 a week\"}."},"signers":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"email":{"description":"Required when delivery is email.","type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"description":"The template role this signer fills, e.g. \"tenant\". Without roles, signers fill the template's roles in order.","type":"string","maxLength":50},"delivery":{"default":"email","description":"email: squiggli emails the signing link and reminders. link: no emails; show signing_url yourself or embed it.","type":"string","enum":["email","link"]},"order":{"description":"Signing order when signing_order is sequential (1 signs first). Defaults to list order.","type":"integer","minimum":1,"maximum":20},"access_code":{"description":"A code the signer must enter before they can see the document. Give it to them another way (phone, SMS, in person): it identifies them by more than the link. Recommended for delivery \"link\".","type":"string","minLength":4,"maxLength":64}},"required":["name"]}},"fields":{"maxItems":500,"type":"array","items":{"type":"object","properties":{"signer":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"string","minLength":1}],"description":"Which signer fills it: their index in signers[] (0 is the first), their role, or their email."},"document":{"default":0,"description":"Index into documents[]. Default 0.","type":"integer","minimum":0,"maximum":9007199254740991},"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"]},"page":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"1 is the first page."},"x":{"type":"number","minimum":0,"description":"PDF points from the left edge of the page (A4 is 595 x 842 points)."},"y":{"type":"number","minimum":0,"description":"PDF points from the top edge of the page."},"width":{"description":"Points. Defaults by type: signature 200, initials 60, checkbox 14, others 160.","type":"number","exclusiveMinimum":0,"maximum":1000},"height":{"description":"Points. Defaults by type: signature 50, initials 32, checkbox 14, others 22.","type":"number","exclusiveMinimum":0,"maximum":500},"required":{"description":"Default true, except checkboxes.","type":"boolean"},"label":{"type":"string","maxLength":100},"key":{"description":"Your own name for the field. Returned with its value in GET /v1/envelopes/{id}.","type":"string","maxLength":100},"value":{"description":"Prefill a text field. The signer can change it.","type":"string","maxLength":1000}},"required":["signer","type","page","x","y"],"description":"A field placed on a PDF page. Template documents bring their own fields."}},"signing_order":{"default":"parallel","description":"parallel: everyone gets it at once. sequential: one after another, by order.","type":"string","enum":["parallel","sequential"]},"deadline":{"description":"Signing deadline (ISO 8601). After it the envelope expires.","type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"deadline_days":{"description":"Deadline as days from sending, instead of deadline.","type":"integer","minimum":1,"maximum":365},"reminders":{"anyOf":[{"type":"boolean","const":false},{"type":"object","properties":{"every_days":{"description":"Remind unsigned signers every N days. null for none. Default 3.","anyOf":[{"type":"integer","minimum":1,"maximum":30},{"type":"null"}]},"before_deadline_days":{"description":"Also remind this many days before the deadline. Default [1].","maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":60}},"max":{"description":"At most this many reminders per signer. Default 5.","type":"integer","minimum":0,"maximum":20}}}],"description":"Automatic reminder emails. false turns them off."},"test":{"description":"Test envelope: free and unlimited, watermarked \"TEST - NOT LEGALLY BINDING\". Always true with a sq_test_ key.","type":"boolean"},"whitelabel":{"description":"No squiggli name or footer anywhere signers look: your business's name and colour only. $1.50 instead of $1.00.","type":"boolean"},"sender":{"description":"Who signers are told sent it (\"Ava Chen sent you...\"), and who gets the decline and completed emails. Defaults to the business.","type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"}},"required":["name"]},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value data (up to 20 keys), e.g. {\"job_id\": \"J-1042\"}. Returned with the envelope and in webhooks."},"redirect_url":{"description":"Where the signing page sends a signer after they sign.","type":"string","format":"uri"},"send":{"default":false,"description":"true sends it now. false keeps a draft to send with POST /v1/envelopes/{id}/send.","type":"boolean"}},"required":["title","signers"]},"CreateTemplate":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1000},"blocks":{"description":"A block document: squiggli lays it out on A4. Text can use {{variables}}.","maxItems":500,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"text":{"type":"string","maxLength":300},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"text":{"type":"string","maxLength":10000},"align":{"type":"string","enum":["left","center"]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"list"},"items":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":2000}},"ordered":{"type":"boolean"}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","const":"table"},"rows":{"maxItems":100,"type":"array","items":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":500}}},"header":{"type":"boolean"}},"required":["type","rows"]},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"height":{"type":"number","minimum":0,"maximum":400}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"page_break"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["initials","date_signed","name","email","text","checkbox"]},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":200},"required":{"type":"boolean"},"key":{"type":"string","maxLength":100},"width":{"type":"number","exclusiveMinimum":0,"maximum":483}},"required":["type","field","role"]},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["type","role"]}]}},"file_base64":{"description":"Or a PDF (base64) with fields placed on it.","type":"string","maxLength":14000000},"file_url":{"type":"string","format":"uri"},"fields":{"description":"Fields on the PDF, by role. Only with file_base64 or file_url.","maxItems":500,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"]},"page":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"1 is the first page."},"x":{"type":"number","minimum":0,"description":"PDF points from the left edge of the page (A4 is 595 x 842 points)."},"y":{"type":"number","minimum":0,"description":"PDF points from the top edge of the page."},"width":{"description":"Points. Defaults by type: signature 200, initials 60, checkbox 14, others 160.","type":"number","exclusiveMinimum":0,"maximum":1000},"height":{"description":"Points. Defaults by type: signature 50, initials 32, checkbox 14, others 22.","type":"number","exclusiveMinimum":0,"maximum":500},"required":{"description":"Default true, except checkboxes.","type":"boolean"},"label":{"type":"string","maxLength":100},"key":{"description":"Your own name for the field. Returned with its value in GET /v1/envelopes/{id}.","type":"string","maxLength":100},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."}},"required":["type","page","x","y","role"]}},"roles":{"description":"Labels for the roles the fields use. Worked out from the fields when left out.","maxItems":20,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["key"]}}},"required":["name"],"description":"A template: blocks, or a PDF with fields."},"Account":{"type":"object","properties":{"business":{"type":"object"},"sending":{"type":"object","properties":{"can_send":{"type":"boolean"},"add_card_url":{"type":["string","null"]}}},"free_documents":{"type":"object"},"prices":{"type":"object"}}},"Envelope":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"envelope"},"title":{"type":"string"},"status":{"enum":["draft","sent","viewed","signed","declined","voided","expired"]},"test":{"type":"boolean"},"whitelabel":{"type":"boolean"},"deadline":{"type":["string","null"],"format":"date-time"},"reminders":{},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"progress":{"type":"object","properties":{"signers":{"type":"integer"},"signed":{"type":"integer"}}},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"pages":{"type":"array","items":{"type":"object","properties":{"width":{"type":"number"},"height":{"type":"number"}}}}}}},"signers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":["string","null"]},"status":{"enum":["pending","sent","viewed","signed","declined"]},"signing_url":{"type":["string","null"]},"first_viewed_at":{"type":["string","null"]},"signed_at":{"type":["string","null"]},"links":{"type":"array"}}}},"fields":{"type":"array","items":{"type":"object"}},"files":{"type":["object","null"],"properties":{"signed_pdf":{"type":"string"},"certificate":{"type":"string"},"signed_pdf_download":{"type":"string"},"certificate_download":{"type":"string"}}}}}}},"paths":{"/me":{"get":{"summary":"Get account","description":"The business this credential acts for: whether it can send live documents, free documents left, prices.","operationId":"getAccount","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/usage":{"get":{"summary":"Get usage","description":"Documents sent this month (or ?month=YYYY-MM), by kind and source. Billed on the Kiewa statement.","operationId":"getUsage","parameters":[{"name":"month","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}],"responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/settings":{"get":{"summary":"Get branding","description":"The name, colour and logo signers see.","operationId":"getSettings","responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update branding","description":"Change the name, colour, logo or white-label default.","operationId":"updateSettings","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"description":"The name signers see. Default: the business name.","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"brand_color":{"description":"Hex colour (#2340c8, 2340c8 or #24c), used for the signing page button and email button.","anyOf":[{"type":"string","pattern":"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"},{"type":"null"}]},"whitelabel_default":{"description":"New envelopes are white-labelled unless they say otherwise.","type":"boolean"},"notify_email":{"description":"Gets decline, expiry and completed emails for envelopes with no sender email.","anyOf":[{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"logo_base64":{"description":"A PNG logo, base64 (under 500 KB). null removes it.","anyOf":[{"type":"string","maxLength":700000},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes":{"post":{"summary":"Create an envelope","description":"A draft, or sent at once with send: true. Documents are PDFs (file_base64, file_url) or templates (template_id + variables). Live sends: 402 card_required (with add_card_url) when the business has no card and no free documents left; 403 squiggli_not_enabled without a subscription.","operationId":"createEnvelope","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvelope"}}}},"responses":{"201":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List envelopes","description":"Newest first.","operationId":"listEnvelopes","parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated statuses"},{"name":"test","in":"query","schema":{"type":"boolean"}},{"name":"template_id","in":"query","schema":{"type":"string"}},{"name":"metadata[key]","in":"query","schema":{"type":"string"},"description":"Match a metadata value, e.g. metadata[job_id]=J-1042"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"A page of envelopes","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}":{"get":{"summary":"Get an envelope","description":"Everything: documents and page sizes, signers with their status, opens and links, fields and values, deadline, reminders, and download links once signed.","operationId":"getEnvelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update an envelope","description":"Deadline, reminders, metadata and redirect_url any time it is open; title and message while it is a draft.","operationId":"updateEnvelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"deadline":{"description":"Move or clear the deadline. Works on sent envelopes too.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"reminders":{"anyOf":[{"type":"boolean","const":false},{"type":"object","properties":{"every_days":{"description":"Remind unsigned signers every N days. null for none. Default 3.","anyOf":[{"type":"integer","minimum":1,"maximum":30},{"type":"null"}]},"before_deadline_days":{"description":"Also remind this many days before the deadline. Default [1].","maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":60}},"max":{"description":"At most this many reminders per signer. Default 5.","type":"integer","minimum":0,"maximum":20}}}],"description":"Automatic reminder emails. false turns them off."},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value data (up to 20 keys), e.g. {\"job_id\": \"J-1042\"}. Returned with the envelope and in webhooks."},"redirect_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a draft","description":"Only drafts. Void sent envelopes instead.","operationId":"deleteEnvelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/send":{"post":{"summary":"Send a draft","description":"Emails the signers whose turn it is (sequential envelopes go one at a time).","operationId":"sendEnvelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/void":{"post":{"summary":"Void (cancel) an envelope","description":"Signers are emailed that it was cancelled.","operationId":"voidEnvelope","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"description":"Shown to signers in the cancellation email.","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/remind":{"post":{"summary":"Remind signers","description":"A fresh link by email to signers whose turn it is, at most hourly per signer.","operationId":"remindSigners","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"signer_ids":{"description":"Default: every signer whose turn it is and who has not signed.","maxItems":20,"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Who was reminded and who was skipped","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/events":{"get":{"summary":"Audit trail","description":"Every event in order, with IP address and device for signer actions.","operationId":"listEnvelopeEvents","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/documents/{documentId}":{"get":{"summary":"Download a document as sent","description":"The PDF signers see.","operationId":"getDocument","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"Document id (doc_...)"}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/signed.pdf":{"get":{"summary":"Download the signed PDF","description":"Every document with every signature and value, once status is signed.","operationId":"getSignedPdf","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"Signed PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/certificate.pdf":{"get":{"summary":"Download the completion certificate","description":"Who signed, when, from where, and the audit trail.","operationId":"getCertificate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"Certificate PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates":{"get":{"summary":"List templates","description":"","operationId":"listTemplates","responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a template","description":"Blocks (laid out by squiggli on A4, with {{variables}}) or a PDF with fields by role.","operationId":"createTemplate","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplate"}}}},"responses":{"201":{"description":"The template","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/preview":{"post":{"summary":"Preview blocks","description":"Renders unsaved blocks to a PDF.","operationId":"previewBlocks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blocks":{"description":"A block document: squiggli lays it out on A4. Text can use {{variables}}.","maxItems":500,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"text":{"type":"string","maxLength":300},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"text":{"type":"string","maxLength":10000},"align":{"type":"string","enum":["left","center"]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"list"},"items":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":2000}},"ordered":{"type":"boolean"}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","const":"table"},"rows":{"maxItems":100,"type":"array","items":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":500}}},"header":{"type":"boolean"}},"required":["type","rows"]},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"height":{"type":"number","minimum":0,"maximum":400}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"page_break"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["initials","date_signed","name","email","text","checkbox"]},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":200},"required":{"type":"boolean"},"key":{"type":"string","maxLength":100},"width":{"type":"number","exclusiveMinimum":0,"maximum":483}},"required":["type","field","role"]},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["type","role"]}]}}}}}}},"responses":{"200":{"description":"Preview PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}":{"get":{"summary":"Get a template","description":"","operationId":"getTemplate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a template","description":"Send only what changes.","operationId":"updateTemplate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1000},"blocks":{"description":"A block document: squiggli lays it out on A4. Text can use {{variables}}.","maxItems":500,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"text":{"type":"string","maxLength":300},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"text":{"type":"string","maxLength":10000},"align":{"type":"string","enum":["left","center"]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"list"},"items":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":2000}},"ordered":{"type":"boolean"}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","const":"table"},"rows":{"maxItems":100,"type":"array","items":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":500}}},"header":{"type":"boolean"}},"required":["type","rows"]},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"height":{"type":"number","minimum":0,"maximum":400}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"page_break"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["initials","date_signed","name","email","text","checkbox"]},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":200},"required":{"type":"boolean"},"key":{"type":"string","maxLength":100},"width":{"type":"number","exclusiveMinimum":0,"maximum":483}},"required":["type","field","role"]},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["type","role"]}]}},"file_base64":{"description":"Or a PDF (base64) with fields placed on it.","type":"string","maxLength":14000000},"file_url":{"type":"string","format":"uri"},"fields":{"description":"Fields on the PDF, by role. Only with file_base64 or file_url.","maxItems":500,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"]},"page":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"1 is the first page."},"x":{"type":"number","minimum":0,"description":"PDF points from the left edge of the page (A4 is 595 x 842 points)."},"y":{"type":"number","minimum":0,"description":"PDF points from the top edge of the page."},"width":{"description":"Points. Defaults by type: signature 200, initials 60, checkbox 14, others 160.","type":"number","exclusiveMinimum":0,"maximum":1000},"height":{"description":"Points. Defaults by type: signature 50, initials 32, checkbox 14, others 22.","type":"number","exclusiveMinimum":0,"maximum":500},"required":{"description":"Default true, except checkboxes.","type":"boolean"},"label":{"type":"string","maxLength":100},"key":{"description":"Your own name for the field. Returned with its value in GET /v1/envelopes/{id}.","type":"string","maxLength":100},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."}},"required":["type","page","x","y","role"]}},"roles":{"description":"Labels for the roles the fields use. Worked out from the fields when left out.","maxItems":20,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["key"]}}}}}}},"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a template","description":"Envelopes already made from it are not affected.","operationId":"deleteTemplate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/templates/{id}/preview":{"post":{"summary":"Preview a template","description":"Renders it with these variables. Missing variables show as {{name}}.","operationId":"previewTemplate","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},"description":"Values for the template's {{variables}}, e.g. {\"client.name\": \"Ava Chen\", \"rent\": \"$650 a week\"}."}}}}}},"responses":{"200":{"description":"Preview PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"List webhooks","description":"","operationId":"listWebhooks","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a webhook","description":"Events: envelope.sent, envelope.viewed, envelope.signed, envelope.completed, envelope.declined, envelope.voided, envelope.expired. Each POST has Squiggli-Event-Id and Squiggli-Signature: t=<unix>,v1=hex(HMAC-SHA256(secret, \"t.body\")). Retried for about 21 hours.","operationId":"createWebhook","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public https URL that accepts POSTed JSON."},"events":{"description":"Default: every event.","type":"array","items":{"type":"string","enum":["envelope.sent","envelope.viewed","envelope.signed","envelope.completed","envelope.declined","envelope.voided","envelope.expired"]}},"all_envelopes":{"description":"true: every envelope in the business. false (default): only envelopes made with this credential.","type":"boolean"}},"required":["url"]}}}},"responses":{"201":{"description":"The webhook, with its secret (shown once)","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"delete":{"summary":"Delete a webhook","description":"","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook id (whk_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys":{"get":{"summary":"List API keys","description":"Web app session or live key only.","operationId":"listApiKeys","responses":{"200":{"description":"Keys (without the secret part)","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create an API key","description":"Shown once.","operationId":"createApiKey","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":100},"mode":{"default":"live","type":"string","enum":["live","test"]}},"required":["name"]}}}},"responses":{"201":{"description":"The key","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys/{id}":{"delete":{"summary":"Revoke an API key","description":"","operationId":"revokeApiKey","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Key id (key_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/embed-tokens":{"post":{"summary":"Create an embed token","description":"For the editor or one envelope inside your web app. Load embed.js and pass the token.","operationId":"createEmbedToken","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["editor","envelope"],"description":"editor: the template editor. envelope: one envelope (build, review and send it)."},"template_id":{"description":"editor: open this template. Leave out to start a new one.","type":"string"},"envelope_id":{"description":"Required for scope envelope.","type":"string"},"ttl_seconds":{"description":"Default 3600.","type":"integer","minimum":60,"maximum":86400}},"required":["scope"]}}}},"responses":{"201":{"description":"Token and iframe URL","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/card-link":{"post":{"summary":"Get a card link","description":"A Kiewa page where the business saves a card (billing). Comes back to the web app.","operationId":"createCardLink","responses":{"200":{"description":"{ url, expires_at }","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/platform/organisations/{businessId}/me":{"get":{"summary":"Get account (platform)","description":"The business this credential acts for: whether it can send live documents, free documents left, prices.","operationId":"platform_getAccount","responses":{"200":{"description":"Account","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}],"parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"}]}},"/platform/organisations/{businessId}/usage":{"get":{"summary":"Get usage (platform)","description":"Documents sent this month (or ?month=YYYY-MM), by kind and source. Billed on the Kiewa statement.","operationId":"platform_getUsage","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"month","in":"query","schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$"}}],"responses":{"200":{"description":"Usage","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/settings":{"get":{"summary":"Get branding (platform)","description":"The name, colour and logo signers see.","operationId":"platform_getSettings","responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}],"parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"}]},"patch":{"summary":"Update branding (platform)","description":"Change the name, colour, logo or white-label default.","operationId":"platform_updateSettings","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"display_name":{"description":"The name signers see. Default: the business name.","anyOf":[{"type":"string","minLength":1,"maxLength":100},{"type":"null"}]},"brand_color":{"description":"Hex colour (#2340c8, 2340c8 or #24c), used for the signing page button and email button.","anyOf":[{"type":"string","pattern":"^#?([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$"},{"type":"null"}]},"whitelabel_default":{"description":"New envelopes are white-labelled unless they say otherwise.","type":"boolean"},"notify_email":{"description":"Gets decline, expiry and completed emails for envelopes with no sender email.","anyOf":[{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]},"logo_base64":{"description":"A PNG logo, base64 (under 500 KB). null removes it.","anyOf":[{"type":"string","maxLength":700000},{"type":"null"}]}}}}}},"responses":{"200":{"description":"Settings","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes":{"post":{"summary":"Create an envelope (platform)","description":"A draft, or sent at once with send: true. Documents are PDFs (file_base64, file_url) or templates (template_id + variables). Live sends: 402 card_required (with add_card_url) when the business has no card and no free documents left; 403 squiggli_not_enabled without a subscription.","operationId":"platform_createEnvelope","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateEnvelope"}}}},"responses":{"201":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]},"get":{"summary":"List envelopes (platform)","description":"Newest first.","operationId":"platform_listEnvelopes","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"status","in":"query","schema":{"type":"string"},"description":"Comma-separated statuses"},{"name":"test","in":"query","schema":{"type":"boolean"}},{"name":"template_id","in":"query","schema":{"type":"string"}},{"name":"metadata[key]","in":"query","schema":{"type":"string"},"description":"Match a metadata value, e.g. metadata[job_id]=J-1042"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"next_cursor from the previous page"}],"responses":{"200":{"description":"A page of envelopes","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}":{"get":{"summary":"Get an envelope (platform)","description":"Everything: documents and page sizes, signers with their status, opens and links, fields and values, deadline, reminders, and download links once signed.","operationId":"platform_getEnvelope","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]},"patch":{"summary":"Update an envelope (platform)","description":"Deadline, reminders, metadata and redirect_url any time it is open; title and message while it is a draft.","operationId":"platform_updateEnvelope","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"message":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"deadline":{"description":"Move or clear the deadline. Works on sent envelopes too.","anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},{"type":"null"}]},"reminders":{"anyOf":[{"type":"boolean","const":false},{"type":"object","properties":{"every_days":{"description":"Remind unsigned signers every N days. null for none. Default 3.","anyOf":[{"type":"integer","minimum":1,"maximum":30},{"type":"null"}]},"before_deadline_days":{"description":"Also remind this many days before the deadline. Default [1].","maxItems":5,"type":"array","items":{"type":"integer","minimum":1,"maximum":60}},"max":{"description":"At most this many reminders per signer. Default 5.","type":"integer","minimum":0,"maximum":20}}}],"description":"Automatic reminder emails. false turns them off."},"metadata":{"type":"object","propertyNames":{"type":"string","maxLength":100},"additionalProperties":{"type":"string","maxLength":500},"description":"Your own key-value data (up to 20 keys), e.g. {\"job_id\": \"J-1042\"}. Returned with the envelope and in webhooks."},"redirect_url":{"anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}}}}},"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]},"delete":{"summary":"Delete a draft (platform)","description":"Only drafts. Void sent envelopes instead.","operationId":"platform_deleteEnvelope","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}/send":{"post":{"summary":"Send a draft (platform)","description":"Emails the signers whose turn it is (sequential envelopes go one at a time).","operationId":"platform_sendEnvelope","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}/void":{"post":{"summary":"Void (cancel) an envelope (platform)","description":"Signers are emailed that it was cancelled.","operationId":"platform_voidEnvelope","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"description":"Shown to signers in the cancellation email.","type":"string","maxLength":500}}}}}},"responses":{"200":{"description":"The envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}/remind":{"post":{"summary":"Remind signers (platform)","description":"A fresh link by email to signers whose turn it is, at most hourly per signer.","operationId":"platform_remindSigners","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"signer_ids":{"description":"Default: every signer whose turn it is and who has not signed.","maxItems":20,"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"Who was reminded and who was skipped","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}/events":{"get":{"summary":"Audit trail (platform)","description":"Every event in order, with IP address and device for signer actions.","operationId":"platform_listEnvelopeEvents","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}/documents/{documentId}":{"get":{"summary":"Download a document as sent (platform)","description":"The PDF signers see.","operationId":"platform_getDocument","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"},{"name":"documentId","in":"path","required":true,"schema":{"type":"string"},"description":"Document id (doc_...)"}],"responses":{"200":{"description":"PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}/signed.pdf":{"get":{"summary":"Download the signed PDF (platform)","description":"Every document with every signature and value, once status is signed.","operationId":"platform_getSignedPdf","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"Signed PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/envelopes/{id}/certificate.pdf":{"get":{"summary":"Download the completion certificate (platform)","description":"Who signed, when, from where, and the audit trail.","operationId":"platform_getCertificate","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Envelope id (env_...)"}],"responses":{"200":{"description":"Certificate PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/templates":{"get":{"summary":"List templates (platform)","description":"","operationId":"platform_listTemplates","responses":{"200":{"description":"Templates","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}],"parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"}]},"post":{"summary":"Create a template (platform)","description":"Blocks (laid out by squiggli on A4, with {{variables}}) or a PDF with fields by role.","operationId":"platform_createTemplate","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTemplate"}}}},"responses":{"201":{"description":"The template","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/templates/preview":{"post":{"summary":"Preview blocks (platform)","description":"Renders unsaved blocks to a PDF.","operationId":"platform_previewBlocks","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"blocks":{"description":"A block document: squiggli lays it out on A4. Text can use {{variables}}.","maxItems":500,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"text":{"type":"string","maxLength":300},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"text":{"type":"string","maxLength":10000},"align":{"type":"string","enum":["left","center"]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"list"},"items":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":2000}},"ordered":{"type":"boolean"}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","const":"table"},"rows":{"maxItems":100,"type":"array","items":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":500}}},"header":{"type":"boolean"}},"required":["type","rows"]},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"height":{"type":"number","minimum":0,"maximum":400}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"page_break"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["initials","date_signed","name","email","text","checkbox"]},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":200},"required":{"type":"boolean"},"key":{"type":"string","maxLength":100},"width":{"type":"number","exclusiveMinimum":0,"maximum":483}},"required":["type","field","role"]},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["type","role"]}]}}}}}}},"responses":{"200":{"description":"Preview PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}],"parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"}]}},"/platform/organisations/{businessId}/templates/{id}":{"get":{"summary":"Get a template (platform)","description":"","operationId":"platform_getTemplate","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"}],"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]},"patch":{"summary":"Update a template (platform)","description":"Send only what changes.","operationId":"platform_updateTemplate","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":1000},"blocks":{"description":"A block document: squiggli lays it out on A4. Text can use {{variables}}.","maxItems":500,"type":"array","items":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"heading"},"text":{"type":"string","maxLength":300},"level":{"anyOf":[{"type":"number","const":1},{"type":"number","const":2},{"type":"number","const":3}]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"paragraph"},"text":{"type":"string","maxLength":10000},"align":{"type":"string","enum":["left","center"]}},"required":["type","text"]},{"type":"object","properties":{"type":{"type":"string","const":"list"},"items":{"maxItems":100,"type":"array","items":{"type":"string","maxLength":2000}},"ordered":{"type":"boolean"}},"required":["type","items"]},{"type":"object","properties":{"type":{"type":"string","const":"table"},"rows":{"maxItems":100,"type":"array","items":{"maxItems":8,"type":"array","items":{"type":"string","maxLength":500}}},"header":{"type":"boolean"}},"required":["type","rows"]},{"type":"object","properties":{"type":{"type":"string","const":"divider"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"spacer"},"height":{"type":"number","minimum":0,"maximum":400}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"page_break"}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","const":"field"},"field":{"type":"string","enum":["initials","date_signed","name","email","text","checkbox"]},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":200},"required":{"type":"boolean"},"key":{"type":"string","maxLength":100},"width":{"type":"number","exclusiveMinimum":0,"maximum":483}},"required":["type","field","role"]},{"type":"object","properties":{"type":{"type":"string","const":"signature"},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["type","role"]}]}},"file_base64":{"description":"Or a PDF (base64) with fields placed on it.","type":"string","maxLength":14000000},"file_url":{"type":"string","format":"uri"},"fields":{"description":"Fields on the PDF, by role. Only with file_base64 or file_url.","maxItems":500,"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["signature","initials","date_signed","name","email","text","checkbox"]},"page":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"1 is the first page."},"x":{"type":"number","minimum":0,"description":"PDF points from the left edge of the page (A4 is 595 x 842 points)."},"y":{"type":"number","minimum":0,"description":"PDF points from the top edge of the page."},"width":{"description":"Points. Defaults by type: signature 200, initials 60, checkbox 14, others 160.","type":"number","exclusiveMinimum":0,"maximum":1000},"height":{"description":"Points. Defaults by type: signature 50, initials 32, checkbox 14, others 22.","type":"number","exclusiveMinimum":0,"maximum":500},"required":{"description":"Default true, except checkboxes.","type":"boolean"},"label":{"type":"string","maxLength":100},"key":{"description":"Your own name for the field. Returned with its value in GET /v1/envelopes/{id}.","type":"string","maxLength":100},"role":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."}},"required":["type","page","x","y","role"]}},"roles":{"description":"Labels for the roles the fields use. Worked out from the fields when left out.","maxItems":20,"type":"array","items":{"type":"object","properties":{"key":{"type":"string","minLength":1,"maxLength":50,"description":"Signer role, e.g. \"tenant\" or \"landlord\"."},"label":{"type":"string","maxLength":100}},"required":["key"]}}}}}}},"responses":{"200":{"description":"The template","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]},"delete":{"summary":"Delete a template (platform)","description":"Envelopes already made from it are not affected.","operationId":"platform_deleteTemplate","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/templates/{id}/preview":{"post":{"summary":"Preview a template (platform)","description":"Renders it with these variables. Missing variables show as {{name}}.","operationId":"platform_previewTemplate","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Template id (tpl_...)"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"variables":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":2000},{"type":"number"},{"type":"boolean"}]},"description":"Values for the template's {{variables}}, e.g. {\"client.name\": \"Ava Chen\", \"rent\": \"$650 a week\"}."}}}}}},"responses":{"200":{"description":"Preview PDF","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/webhooks":{"get":{"summary":"List webhooks (platform)","description":"","operationId":"platform_listWebhooks","responses":{"200":{"description":"Webhooks","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}],"parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"}]},"post":{"summary":"Create a webhook (platform)","description":"Events: envelope.sent, envelope.viewed, envelope.signed, envelope.completed, envelope.declined, envelope.voided, envelope.expired. Each POST has Squiggli-Event-Id and Squiggli-Signature: t=<unix>,v1=hex(HMAC-SHA256(secret, \"t.body\")). Retried for about 21 hours.","operationId":"platform_createWebhook","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Public https URL that accepts POSTed JSON."},"events":{"description":"Default: every event.","type":"array","items":{"type":"string","enum":["envelope.sent","envelope.viewed","envelope.signed","envelope.completed","envelope.declined","envelope.voided","envelope.expired"]}},"all_envelopes":{"description":"true: every envelope in the business. false (default): only envelopes made with this credential.","type":"boolean"}},"required":["url"]}}}},"responses":{"201":{"description":"The webhook, with its secret (shown once)","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/webhooks/{id}":{"delete":{"summary":"Delete a webhook (platform)","description":"","operationId":"platform_deleteWebhook","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Webhook id (whk_...)"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}},"/platform/organisations/{businessId}/embed-tokens":{"post":{"summary":"Create an embed token (platform)","description":"For the editor or one envelope inside your web app. Load embed.js and pass the token.","operationId":"platform_createEmbedToken","parameters":[{"name":"businessId","in":"path","required":true,"schema":{"type":"string"},"description":"The Kiewa business id"},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Send one on every write. A repeat with the same key returns the first answer (24 hours)."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["editor","envelope"],"description":"editor: the template editor. envelope: one envelope (build, review and send it)."},"template_id":{"description":"editor: open this template. Leave out to start a new one.","type":"string"},"envelope_id":{"description":"Required for scope envelope.","type":"string"},"ttl_seconds":{"description":"Default 3600.","type":"integer","minimum":60,"maximum":86400}},"required":["scope"]}}}},"responses":{"201":{"description":"Token and iframe URL","content":{"application/json":{"schema":{"type":"object"}}}},"4XX":{"description":"Error. message says what went wrong and how to fix it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"tags":["platform"],"security":[{"platform":[]}]}}}}