{"openapi":"3.0.3","info":{"title":"Sign&Grow API","version":"1.0.0","description":"Everything the Sign&Grow app does goes through this API. It is the same on every plan, keys work immediately, and there is no separate test environment or go-live review. All times are ISO 8601 in UTC. Errors are JSON: {\"error\": \"what went wrong and what to do\"}. Sending answers 402 when the account has too few signatures left: one is held for each person who signs, it is only used when they sign, and nothing is ever charged automatically. Every call that emails a recipient (sending, a correction, a reminder, reopening, a bulk send) shares three rules that keep scammers out, and each answers with what to do: 403 while sending is paused on the account, with the reason; 422 when the request reads like a fake payment notice or goes out under the name of a well-known brand, with the words that set it off; 429 when it would newly email more people than the daily limit, with when there is room again. The second and third apply to an account until it has a payment that is at least 14 days old and was not refunded or disputed, or until a person has cleared it: paying does not lift them at once. The same rules are asked again when the email to the next person in a signing order is written. If they say no then (the account was paused meanwhile, say), that person is not asked yet, the audit trail has a \"Held back\" line, the envelope carries \"held_at\", and they are asked by themselves once the reason is gone. A team invitation is an email too: it has the same rules, with a daily limit of its own (see POST /account/invites). Stored files are checked whenever they are read: a file whose stored copy fails its check answers 500 with \"code\": \"file_damaged\" and is never sent, and one locked with an encryption key the server was not given answers 503 with \"code\": \"file_locked\". A call that stores a file (an upload, a signer's attachment, a correction that keeps a copy of what someone signed) answers 503 with \"code\": \"storage_stopped\" while the server refuses to store new files because its encryption key cannot read the files already there; nothing is saved, and the same call works again once the operator has set the right key."},"servers":[{"url":"https://growsigning.com/api"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from Settings, API and webhooks. Send it as \"Authorization: Bearer tsk_...\". Every key has a scope. \"send\", the default, covers envelopes, templates, files, contacts, bulk sends, export and reports, and can read the webhook list and delivery log without the signing secrets. \"admin\" is chosen on purpose when the key is created and also covers account settings, invitations and webhooks; it only works while its creator is an admin. No key of either scope can create or revoke keys, remove a team member, hand over or close the account, see or change the ways its creator signs in (everything under /me/signin: a password link, Google or Microsoft), see or change two-step login (every route with two-step in its path), or change the plan, pay or refund. Those answer 403 and need a person signed in to the app. A key that cannot be used answers 401 and says which it is: the header could not be read, the key is unknown or revoked, or the person who created it has left the account. While an account is being closed, or the person who created a key is closing their own login, the key answers 403 until that person signs in again. When a key stops because its creator left a team, by being removed or by closing their login, the admins of the team get an email that names it. Two-step login does not apply to keys: a key is never asked for a code, also not in an account that requires two-step login of its members, so treat a key like a password."}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"What went wrong and what to do about it, written for people."},"request_id":{"type":"string","description":"Also sent as the X-Request-Id header. Quote it when asking for help."}}},"File":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"pages":{"type":"integer"},"size":{"type":"integer","description":"Bytes of the stored PDF. Every signer downloads all of it. From 5 MB the app's editor tells the sender that it is slow to open on a phone."},"page_sizes":{"type":"array","items":{"type":"object","properties":{"w":{"type":"number"},"h":{"type":"number"}}}},"is_scan":{"type":"boolean","description":"true when at least one page is a picture with no text: a scan, a photo, or any PNG or JPEG upload. Such pages cannot be searched or read out by a screen reader."},"scan_pages":{"type":"array","items":{"type":"integer"},"description":"The pages that have no text, counted from 1. Empty when every page has text. Kept with the file and repeated on every document that uses it."}}},"Document":{"type":"object","required":["file_id"],"properties":{"id":{"type":"string","description":"Your own id, used by fields to point at this document. Optional."},"file_id":{"type":"string"},"name":{"type":"string"},"pages":{"type":"integer","readOnly":true},"is_scan":{"type":"boolean","readOnly":true,"description":"The scan flag of the file, as on File."},"scan_pages":{"type":"array","items":{"type":"integer"},"readOnly":true,"description":"The pages of the file that have no text, counted from 1."}}},"Recipient":{"type":"object","required":["name"],"properties":{"id":{"type":"string","description":"Your own id, used by fields to point at this recipient."},"role":{"type":"string","enum":["signer","approver","cc","viewer","inperson","witness"],"default":"signer"},"role_name":{"type":"string","description":"Templates only: the name of the role, such as \"Client\"."},"name":{"type":"string"},"email":{"type":"string","format":"email","description":"Needed to send, except for a recipient with \"link_by_sender\". Empty for that person."},"routing_order":{"type":"integer","minimum":1,"default":1},"link_by_sender":{"type":"boolean","default":false,"description":"\"I will send the link myself\": a person with a name and no email address, for an envelope (not a template) and the roles signer, approver and viewer. Nothing is ever emailed to them: no invitation, reminder or copy. Get their link with POST /envelopes/{id}/recipient-view and pass it on yourself; the same link opens the completed document. The audit trail and the certificate say \"Link shared by the sender\". They count towards the daily limit on new people and, if they sign, use a signature like anyone who is not the sender. Refused with 400 together with an email address, a code by email (\"verify\": \"email_code\"), \"text_link\" or an email field. Leaving it out keeps what is saved, except that giving the person an email address clears it. Answers carry 1 or 0."},"access_code":{"type":"string","nullable":true,"minLength":4,"description":"The signer must type this before the document opens. You give it to them yourself; it is never in our emails. At least 4 characters: a shorter one is refused with 400 when the envelope is sent or corrected. After 10 wrong tries the code is frozen and opens nothing until you set a different one."},"note":{"type":"string","nullable":true},"code_frozen_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Set when the access code was frozen after too many wrong tries. Setting a new access_code clears it."},"verify":{"type":"string","enum":["none","email_code","sms_code"],"default":"none","description":"A check the recipient has to pass before the document opens, besides the link and the access code. \"email_code\" sends a 6-digit one-time code to their email address, \"sms_code\" by text message to \"phone\". The code is sent when the person asks for it on the signing page, works for 10 minutes and 5 tries, and is never part of any answer of this API. An access_code can be combined with either and is asked for first. \"sms_code\" is refused with 400 and \"code\": \"texts_off\" when the operator of this server has not switched text messages on (GET /me says so in text_messages). Leaving it out keeps what the recipient has. Changing it on an envelope that is out makes the person pass the check again and is written to the audit trail."},"phone":{"type":"string","nullable":true,"description":"A mobile number in international form (E.164): a plus sign, the country code and the number, such as \"+447700900123\". Spaces, dashes and brackets are forgiven. Needed for \"sms_code\" and for \"text_link\", refused with 400 when it is missing or not a full number at the time the envelope is sent or corrected. Kept on this recipient and nowhere else, and never shown whole to whoever holds the signing link. When a correction changes the email address to another person's, send their phone in the same call: a number typed for one person is never used for another."},"text_link":{"type":"boolean","default":false,"description":"Also send the signing link by text message to \"phone\", when the request goes out and with reminders (at most one reminder by text a day). Needs text messages to be switched on, like \"sms_code\". A text counts like an email to that person: none while the account is paused, and an account under the daily limit can text as many phone numbers a day as it may email people. Not for someone who signs in person."},"check":{"type":"object","readOnly":true,"description":"How this recipient was checked so far.","properties":{"line":{"type":"string","description":"The sentence the certificate of completion carries for this person, such as \"Link sent by email only\" or \"One-time code sent by text message to +44 *** *** 0123, passed 12 March 2026 14:02 UTC\"."},"passed_at":{"type":"string","format":"date-time","nullable":true,"description":"When the one-time code was typed in correctly by whoever holds the link now. Empty until then, and again after the check, the number or the person changes."},"stopped":{"type":"boolean","description":"true when someone using the link said the mobile number is not theirs. No code is sent to it until you correct the number or the check."}}},"status":{"type":"string","enum":["pending","sent","viewed","completed","declined"],"readOnly":true},"sent_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"viewed_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"completed_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"muted":{"type":"integer","readOnly":true,"description":"1 when the recipient turned reminders off."},"bounced_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Set when an email to this person came back for good (the address or the domain does not exist, or the mailbox refuses), or said \"try later\" on 3 separate days. No reminder goes to them until the address is changed or you call POST /envelopes/{id}/try-again. Changing the email address clears it. Always empty on a server that is not told about bounces."},"bounce_reason":{"type":"string","nullable":true,"readOnly":true,"description":"Why, in plain words, such as \"no such mailbox\"."},"complained_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Set when this person marked one of our emails about this envelope as spam. Nothing more is emailed to them about it (no reminder, no notice of a change, no completed copy), and it counted as one report against the sending account. Only the person can undo it, on their signing page. Their link keeps working."},"group_id":{"type":"string","nullable":true,"description":"Make this recipient one of your signing groups (GET /groups): a group of 2 to 20 people, any one of whom can act for it, for the roles signer, approver, viewer and cc (not inperson). Its name comes from the group and it has no email of its own: whatever \"name\" and \"email\" say is not read. Not with \"verify\" or \"text_link\", which go to one person; an access_code is one for the whole group. On a draft or template it follows the saved group. When the envelope is sent the members are written down as they are then, and changing or deleting the group later does not change it. Leave it out to keep what the recipient is, send null to make it a person. It is one recipient everywhere else: one place in the order, one signature held while it is out and one used when it signs."},"group_name":{"type":"string","nullable":true,"readOnly":true,"description":"The name of the group, for a group recipient."},"group_missing":{"type":"boolean","readOnly":true,"description":"On a draft or template: true when the group it names was deleted. It cannot be sent like that."},"members":{"type":"array","description":"A group recipient's members: on a draft or template the saved group as it is now, on an envelope that is out the people it went out with, each with \"sent_at\", \"viewed_at\" and \"muted\". Never their links. On PUT /envelopes/{id} of an envelope that is out, send a full list of {name, email} to change who can act: someone added is emailed their own link at once, someone taken out loses theirs and is told, and if that was the person who had taken it on, the whole group is asked again. Members of a group that has finished cannot change.","items":{"type":"object","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string"},"email":{"type":"string","format":"email"},"sent_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"viewed_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"muted":{"type":"integer","readOnly":true}}}},"claimed_by":{"type":"string","nullable":true,"readOnly":true,"description":"For a group recipient: the member (members[].id) who took the document on, by being the first to agree to sign it. From then \"name\" and \"email\" are that person's, the others' links say who has it, and the audit trail and the certificate name both (\"Maya Lopez, for HR team\"). Empty while nobody has."},"claimed_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"witness_for":{"type":"string","nullable":true,"description":"For the role \"witness\": the id of the person who signs (role \"signer\" or \"inperson\", not a group) whose signature this witness watches, as the same request names that person. One witness for each person who signs. The witness is asked straight after that person has signed, whatever the signing order says, and nobody else in the order waits for them. A witness never uses a signature, also not when the signer's does. They need a signature field of their own: the app's editor places a block of five fields near the signer's signature (signature, name, address, occupation and the date), and through the API place what you need, at least a signature field. Their name and email address print on the pages only once they have witnessed, so changing the witness is not a change to what the signer signed. Sending refuses, with 400 and the reason, a witness for nobody, for someone who does not sign, a second witness for one person, a group, a witness with \"link_by_sender\", a witness who is the signer, and a witness without a signature field. Sign&Grow records what the witness states, when they stated it, and from which internet address and browser. It cannot check that they were in the room. Whether a document witnessed this way is accepted depends on the law that applies to it and on whoever it is for. For a deed, check that first."},"named_by_signer":{"type":"boolean","default":false,"description":"For the role \"witness\": leave \"name\" and \"email\" out and the person they witness names them on the signing page before Finish (POST /sign/{token}/witness), with a paragraph on who may be a witness. Until then the row carries a name like \"Witness for Ann Lee\" and no email. On a draft or a template, a name or an email sent together with true is refused with 400. A bulk row or a public form does not fill such a witness in. Answers carry 1 or 0."},"witness_statement":{"type":"string","nullable":true,"readOnly":true,"description":"The witness's own statement, exactly as they ticked it: \"I was physically present and saw {signer} sign this document on {date}.\" The date is the signer's date of signing, in the envelope's date format. A statement about a signature that was later set aside (the signer was asked to sign again) no longer stands, and the witness is asked again."},"witness_said_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"When the witness ticked their statement."},"witness_absent_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Set when the witness said \"I was not there\" (POST /sign/{token}/not-present). Nothing of theirs is signed, the signer and the sender are emailed, and the envelope stays out, unwitnessed, until another witness has signed: the signer can name one, or the sender can change the witness with POST /envelopes/{id}/correct or by changing the envelope. Cleared when another person takes the place."},"witness_marks":{"type":"string","nullable":true,"readOnly":true,"description":"Set when the witness finished: \"address\" when they witnessed with the signer's own email address, \"device\" when they finished in the same browser as the signer, \"network\" when they finished from the same internet address with the same kind of browser. Comma separated. Each is allowed, printed on the certificate of completion, written to the audit trail and emailed to the sender, because that is what a challenge to the document would look at."}}},"Group":{"type":"object","required":["name","members"],"description":"A signing group the account keeps: a name and 2 to 20 members, each with a name and an email address of their own (an address can be in a group once). Everyone on the team can read and use them, only admins can change them. An account keeps up to 200.","properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","maxLength":80,"description":"Unique in the account, whatever the case."},"members":{"type":"array","minItems":2,"maxItems":20,"items":{"type":"object","required":["name","email"],"properties":{"id":{"type":"string","readOnly":true},"name":{"type":"string","maxLength":120},"email":{"type":"string","format":"email"}}}},"used_by":{"type":"integer","readOnly":true,"description":"How many drafts and templates name it."}}},"Field":{"type":"object","required":["document_id","type","page","x","y","w","h"],"description":"Positions and sizes are fractions of the page, measured from its top left corner.","properties":{"id":{"type":"string","description":"Optional."},"document_id":{"type":"string"},"recipient_id":{"type":"string","description":"Not used for a \"note\" or a \"strike\": those belong to nobody and everyone is shown them, so a recipient_id sent with one is not read."},"type":{"type":"string","enum":["signature","initials","date_signed","full_name","email","text","number","date","company","title","checkbox","radio","dropdown","attachment","note","strike"]},"page":{"type":"integer","minimum":0,"description":"First page is 0."},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1},"required":{"type":"boolean","default":true},"label":{"type":"string"},"value":{"type":"string","nullable":true},"options":{"type":"array","items":{"type":"string"},"description":"For dropdowns."},"group_name":{"type":"string","description":"Radio buttons with the same group are one choice."},"validation":{"type":"string","description":"email, number, phone, or a regular expression. A field of type \"number\" is always checked as a number, written the way people write numbers: 2500, 12.5, 1,234.56, 1.234,56, 1 234,56, 1'234.56, 1,23,456, with a currency sign before or after if they like. What was typed is stored and printed as typed."},"readonly":{"type":"boolean"},"show_when":{"type":"object","nullable":true,"required":["field","is"],"description":"Only show this field when another field of the same recipient has a certain answer. \"field\" names that field by the id you gave it in the same request, its stored id, or its label when exactly one field has that label; it is given back as the stored id. \"is\": \"checked\" or \"unchecked\" for a checkbox or a radio button (that button chosen), \"equals\" or \"not_equals\" for a dropdown, a text, a company or a job title (letter case and extra spaces do not matter), \"filled\" or \"empty\" for those and for a date or an attachment, and for a number field (also a calculated one) \"equals\", \"not_equals\", \"more_than\" or \"less_than\", compared as numbers. \"value\" is what it is compared with. Rules can depend on fields that have rules of their own: a field is only shown when the field it depends on is shown too. A field that is not shown is not required, keeps no answer (it goes back to what you put there, or empty) and prints nothing on the signed PDF. The server works this out from what is stored when the signer saves and finishes, whatever the browser sends. Refused with 400, naming the fields and saving nothing: a field of another recipient, a note or a strike-out with a rule, a question the field cannot be asked, a \"value\" that is missing or, for a number, not a number, and rules or formulas that depend on each other in a circle (\"code\": \"logic_loop\", with \"fields\"). Once someone has finished, changing a rule changes what they signed: it needs \"resign\": true like any change to what is printed (PUT /envelopes/{id}).","properties":{"field":{"type":"string"},"is":{"type":"string","enum":["checked","unchecked","filled","empty","equals","not_equals","more_than","less_than"]},"value":{"type":"string","description":"For equals, not_equals, more_than and less_than. At most 200 characters."}},"example":{"field":"has_cosigner","is":"checked"}},"formula":{"type":"string","nullable":true,"description":"For a field of type \"number\": its value is worked out from other number fields of the envelope (any recipient's), and nobody types it. Fields go in curly brackets by id or by label, and are given back by id: \"{Quantity} * {Unit price}\". It can use numbers (with a dot before decimals), + - * / (also × ÷), round brackets, sum(a, b, ...) and round(x, decimals) with 0 to 10 decimals, at most 500 characters; nothing in it is ever run as code. An empty field counts as 0, a field that is not shown counts as empty, and when every field it uses is empty it stays empty. Division by 0, a field that does not read as a number, a number of more than 15 digits and a result of 10^15 or more leave it empty, and the signing page says why. The result is written with the decimal mark and thousands mark of the numbers it comes from (1.234,50 stays in that style), and round(x, 2) always shows two decimals. A field of someone else only counts once that person has finished, and a result never changes after its own signer has finished. A calculated field is never required or read only, and a \"value\" sent for it, by the editor, the API or a signer's browser, is not taken: the server works it out. A formula that cannot be read, or that uses a field that is not a number field, is refused with 400.","example":"round({Quantity} * {Unit price}, 2)"}}},"EnvelopeInput":{"type":"object","properties":{"kind":{"type":"string","enum":["envelope","template"],"default":"envelope"},"subject":{"type":"string"},"message":{"type":"string"},"ordered":{"type":"boolean","description":"Sign in routing_order instead of all at once."},"reminder_days":{"type":"integer","minimum":0,"maximum":60,"description":"Days between automatic reminder emails to whoever has their turn and has not finished. 0 sends none. Left out, the account's own default applies, which is 3 for an account made since reminders are on by default (it is \"account.default_reminder_days\" in GET /me). Send 0 if your own system does the reminding."},"expire_days":{"type":"integer","minimum":1,"maximum":365},"date_format":{"type":"string","enum":["YYYY-MM-DD","DD/MM/YYYY","MM/DD/YYYY","D MMM YYYY","MMM D, YYYY"],"description":"How every date on the documents is written: the date each person signs on, which is the calendar day in the time zone their device reports (failing that the sender's zone, then UTC), and any date picked in a date field (sent and stored as YYYY-MM-DD). Left out, a new envelope starts with the account's own format, set under Settings, and failing that with YYYY-MM-DD."},"documents":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"}}}},"Envelope":{"allOf":[{"$ref":"#/components/schemas/EnvelopeInput"},{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"created_at":{"type":"string","format":"date-time","nullable":true},"sent_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true},"expires_at":{"type":"string","format":"date-time","nullable":true},"final_sha256":{"type":"string","nullable":true,"description":"SHA-256 of the signed PDF, once completed."},"pay_url":{"type":"string","nullable":true,"description":"The link to your own payment page that signers are shown after Finish. Set it with PUT /envelopes/{id}/pay-link, not here."},"pay_kind":{"type":"string","nullable":true},"sheets":{"type":"integer","description":"Sheets of paper this envelope saved."},"edit_version":{"type":"integer","readOnly":true,"description":"Counts up with every change to the envelope: a save, a quick correction of one recipient, a signer who passes the document on or fixes their name, and sending. Send it back with PUT to be told when the envelope changed in between."},"edited_by":{"type":"string","nullable":true,"readOnly":true,"description":"Who made the latest change."},"edited_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true},"edited_how":{"type":"string","nullable":true,"readOnly":true,"description":"What the latest change was when it was not a save. It finishes the sentence that starts with edited_by: \"sent this envelope\", \"passed this document on to Mary Deputy\". Empty after a save."},"content_version":{"type":"integer","readOnly":true,"description":"Counts up whenever a correction changes what a signer sees or signs."},"held_at":{"type":"string","format":"date-time","nullable":true,"readOnly":true,"description":"Set while emails about this envelope are held back because the account is paused or the envelope reads like a fake payment notice: when the sender was told. Empty again once they have gone out."},"access":{"allOf":[{"$ref":"#/components/schemas/TemplateAccess"}],"readOnly":true,"description":"Templates, from GET /envelopes/{id}. Set it with PUT /envelopes/{id}/access."},"wording_lock":{"type":"object","nullable":true,"readOnly":true,"description":"Envelopes, from GET /envelopes/{id}: set when it was started from a template whose wording is locked for you. What stays as it is, and who can change the template, is said in PUT /envelopes/{id}.","properties":{"template_id":{"type":"string"},"template":{"type":"string","nullable":true,"description":"Its name, or null when it was deleted since."},"ask":{"type":"string","description":"Who can change it, such as \"Maya Lopez or an admin of your team\"."},"fixed":{"type":"array","items":{"type":"string"},"description":"The ids of the fields that hold wording from the template."}}}}}]},"AuditEvent":{"type":"object","properties":{"seq":{"type":"integer"},"at":{"type":"string","format":"date-time","nullable":true},"actor":{"type":"string"},"action":{"type":"string"},"detail":{"type":"string"},"ip":{"type":"string","nullable":true},"prev_hash":{"type":"string"},"hash":{"type":"string"}}},"TemplateAccess":{"type":"object","description":"Who can use and change a template. GET /envelopes/{id} carries it on a template as \"access\".","properties":{"use":{"type":"string","enum":["team","admins","chosen"]},"change":{"type":"string","enum":["owner","chosen","team"]},"locked":{"type":"boolean"},"owner":{"type":"string","description":"The name of the person it belongs to."},"owner_id":{"type":"string"},"chosen_use":{"type":"array","items":{"type":"string"},"description":"Names of the chosen members who may use it, when \"use\" is \"chosen\"."},"chosen_change":{"type":"array","items":{"type":"string"},"description":"Names of the chosen members who may change it, when \"change\" is \"chosen\"."},"may_use":{"type":"boolean"},"may_change":{"type":"boolean"},"may_delete":{"type":"boolean"},"may_set":{"type":"boolean","description":"Whether the caller may change this rule: the person it belongs to and admins."},"members":{"type":"array","description":"Only for the person it belongs to and admins.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string"},"always":{"type":"boolean","description":"An admin, the owner of the account or the person it belongs to: can always use and change it."},"chosen":{"type":"boolean"},"can_change":{"type":"boolean"}}}}}},"ApiKey":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"prefix":{"type":"string","description":"The first characters of the key. The key itself is shown once, when it is created, and never again."},"scope":{"type":"string","enum":["send","admin"]},"created_at":{"type":"string","format":"date-time","nullable":true},"last_used_at":{"type":"string","format":"date-time","nullable":true},"stopped_at":{"type":"string","format":"date-time","nullable":true,"description":"Set when the key stopped working for good because the person who created it left the account: an admin removed them, or their own login was deleted."},"closing":{"type":"string","format":"date-time","nullable":true,"description":"Set while the person who created the key is closing their login. The key is switched off and answers 403. It works again if they sign in before this time, and stops for good at this time if they do not."},"owner_name":{"type":"string"},"owner_email":{"type":"string","description":"Empty once the login of the person who created the key has been deleted."},"mine":{"type":"boolean"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"integer"},"webhook_id":{"type":"string"},"url":{"type":"string"},"event":{"type":"string"},"envelope_id":{"type":"string"},"state":{"type":"string","enum":["pending","delivered","failed"],"description":"A delivery is listed as pending from before the first try."},"status":{"type":"integer","nullable":true,"description":"The HTTP status your server answered with, if it answered."},"error":{"type":"string","nullable":true},"attempts":{"type":"integer"},"at":{"type":"string","format":"date-time","nullable":true},"can_redeliver":{"type":"boolean","description":"The content of the latest 200 deliveries of each webhook is kept for sending again."}}},"BulkResult":{"type":"object","description":"What a bulk send has done, row by row, read from the batch record.","properties":{"id":{"type":"string","description":"The batch."},"sent":{"type":"integer","description":"Rows that have gone out."},"pending":{"type":"integer","description":"Rows that have not been tried yet. 0 once the batch is done."},"failed":{"type":"array","description":"The rows that could not be sent, each with the reason. A row that got as far as a copy is kept as a draft in the batch.","items":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"}}}},"results":{"type":"array","description":"One entry per row, in the order of the request.","items":{"type":"object","properties":{"ok":{"type":"boolean"},"id":{"type":"string","description":"The envelope, when the row was sent."},"error":{"type":"string","description":"Why the row could not be sent."},"pending":{"type":"boolean","description":"true while the row has not been tried yet."}}}},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SendWarning"},"description":"What the check before sending found in the template, said once for the whole batch. It never stops a row."}}},"SendWarning":{"type":"object","description":"One finding of the check before sending: a word that names a kind of document which often needs ink on paper, a witness, a notary or a qualified signature. A reminder, never a refusal, and not legal advice. At most one finding for each kind of document.","properties":{"kind":{"type":"string","enum":["will","trust","attorney","land","employment","witness"]},"word":{"type":"string","description":"The word on our list that matched."},"seen":{"type":"string","description":"The same word as it stands in the subject or the document."},"where":{"type":"string","enum":["subject","document name","document text"]},"document":{"type":"string","nullable":true,"description":"The name of the document, when the word was in a document's name or text."},"found":{"type":"string","description":"What was seen, as a sentence."},"why":{"type":"string","description":"Why that kind of document is on the list."},"message":{"type":"string","description":"The whole warning, written for a person: what was found, why it matters, and that nothing is blocked."},"help":{"type":"string","description":"Where the help page explains it, as a path."},"help_url":{"type":"string","format":"uri","description":"The same as a full address."}}},"CommentThread":{"type":"object","description":"A conversation in the comments of an envelope that is out. Comments are not printed on the document and are not part of what is signed. The record of the document says that a comment was written, by whom and when, never what it says.","properties":{"id":{"type":"string"},"private":{"type":"boolean","description":"true: only the sender's side and the person in \"with\" can read it. false: everyone on the envelope can."},"with":{"type":"object","nullable":true,"properties":{"recipient_id":{"type":"string"},"name":{"type":"string"}},"description":"The one person a private thread is with. When their place on the envelope passes to someone else (a hand-over, a correction to another address), the thread stays with the person it was with: the next one never sees it."},"pin":{"type":"object","nullable":true,"properties":{"document_id":{"type":"string"},"document":{"type":"string"},"page":{"type":"integer","description":"Counted from 0."},"x":{"type":"number","minimum":0,"maximum":1,"nullable":true},"y":{"type":"number","minimum":0,"maximum":1,"nullable":true}}},"pin_words":{"type":"string"},"waiting":{"type":"boolean","description":"true when the last word is from someone on the envelope and nobody has marked it as settled: they are waiting for an answer."},"settled_at":{"type":"string","format":"date-time","nullable":true},"settled_by":{"type":"string","nullable":true},"comments":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"by_sender":{"type":"boolean"},"name":{"type":"string"},"email":{"type":"string","nullable":true},"recipient_id":{"type":"string","nullable":true},"body":{"type":"string"},"at":{"type":"string","format":"date-time","nullable":true},"news":{"type":"array","description":"Who is to be emailed about this comment and what became of it: \"mailed_at\" once it went, \"not_emailed\" with the reason when it never will, both empty while it waits.","items":{"type":"object","properties":{"to":{"type":"string"},"mailed_at":{"type":"string","format":"date-time","nullable":true},"not_emailed":{"type":"string","nullable":true}}}}}}}}},"CommentEvent":{"type":"object","properties":{"id":{"type":"string"},"thread_id":{"type":"string"},"private":{"type":"boolean"},"with_recipient_id":{"type":"string","nullable":true},"by_sender":{"type":"boolean"},"name":{"type":"string"},"text":{"type":"string"},"at":{"type":"string","format":"date-time","nullable":true},"pin":{"type":"object","nullable":true}}},"WebhookEvent":{"type":"object","description":"POSTed to your webhook URL. Verify the X-SignAndGrow-Signature header: \"sha256=\" + HMAC-SHA256(secret, X-SignAndGrow-Timestamp + \".\" + raw body).","properties":{"id":{"type":"string","description":"Unique per event. A delivery that is sent again keeps the same id, so repeats can be ignored."},"event":{"type":"string","enum":["envelope.sent","envelope.completed","envelope.declined","envelope.voided","envelope.expired","envelope.corrected","envelope.updated","recipient.viewed","recipient.completed","comment.created"]},"created_at":{"type":"string","format":"date-time","nullable":true},"text":{"type":"string","description":"A one-line summary."},"recipient_id":{"type":"string"},"envelope":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"subject":{"type":"string"},"sent_at":{"type":"string","format":"date-time","nullable":true},"completed_at":{"type":"string","format":"date-time","nullable":true}}},"comment":{"$ref":"#/components/schemas/CommentEvent","description":"With \"comment.created\" only: the comment that was written, by someone on the envelope (recipient_id says who) or by the sender's side."}}}}},"paths":{"/files":{"post":{"summary":"Upload a PDF, PNG or JPEG (up to 25 MB, 500 pages)","description":"A picture becomes a one-page PDF on an A4 page, upright or on its side to suit the picture. A JPEG that carries a camera orientation note (EXIF) is turned upright, so a phone photo is the same way up on screen and in the signed PDF. Send the field \"file\" more than once to make one document from several pictures, a page for each, in the order sent: PNG and JPEG only, up to 50 pictures and 25 MB together. A PNG can have up to 25 million pixels and a JPEG up to 50 million, counted from the picture's header; a larger one is refused with a 400 that names it. Pictures are stored as sent: the app's own editor makes large photos smaller before it uploads them (2000 pixels on the long side), the API does not.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The file. Repeat the field to join several pictures into one document."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/File"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes":{"get":{"summary":"List envelopes or templates","description":"A member gets the envelopes they sent and the folders those are in. An admin gets every envelope in the account. Templates are shared with the team: everyone gets every template they may use (see GET /envelopes/{id}/access), and a template that is for admins only or for chosen members, and its folder, is left out for everyone else. Each template carries \"may_change\", which says whether the caller may change it, and \"access\": {use, change, locked, may_use, may_change, may_delete, may_set}. A completed envelope that its sender deleted, or one somebody had signed before it was voided, declined or ran out of time, is not listed. For admins the answer also carries \"removed\": how many such envelopes the account holds, and box=removed lists them (403 for a member), each with \"removed_at\"; POST /envelopes/{id}/restore puts one back.","parameters":[{"name":"kind","in":"query","schema":{"type":"string","enum":["envelope","template"]}},{"name":"box","in":"query","description":"\"removed\" is for admins only: the envelopes their sender deleted after somebody had signed. They are in no other box, search, export or report, and can be searched with q in here.","schema":{"type":"string","enum":["all","drafts","sent","waiting","completed","closed","removed"]}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search. Every word (up to 8) has to be found somewhere: in the subject, the folder, the name or address of a person, the name of a role, the name of a document or the words inside it. The whole text also finds an envelope by its id. Works for templates as well, with kind=template."},{"name":"folder","in":"query","schema":{"type":"string"},"description":"Only what is in this folder. Folders of templates belong to the team. PATCH /envelopes/{id} with {\"folder\": \"...\"} moves an envelope or a template, and an empty folder takes it out."},{"name":"limit","in":"query","schema":{"type":"integer","maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"envelopes":{"type":"array","items":{"$ref":"#/components/schemas/Envelope"}},"folders":{"type":"array","items":{"type":"string"}},"removed":{"type":"integer","description":"Admins only, on envelopes: how many envelopes of the account were removed by their sender. Left out for members and for templates."}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a draft, or create from a template; add \"send\": true to send it at once","description":"The body is checked like the body of PUT /envelopes/{id}: a part that cannot be carried out as it is written (a \"kind\" that does not exist, a page the document does not have, text over its limit, a list that is not a list, a \"send\" that is not true or false, and the rest named there) answers 400, names the part, and no draft is left behind. \"send\": \"false\", in quotes, is refused and sends nothing.","parameters":[{"name":"Idempotency-Key","in":"header","description":"Any string of up to 200 characters that you make up for this one call. Repeating the call with the same key and the same body returns the envelope the first call made, as it is now and with the header \"Idempotent-Replay: true\", instead of creating or sending another. A key belongs to whoever sent it: you, or the person who created the API key. The same text used by another member of your team is their own key and never returns your envelope. The same key with a different body answers 409 and creates nothing. A key lasts as long as its envelope: once the envelope is deleted, or a create-and-send is refused, the key is free and the next call with it makes a new envelope. Without the header every call makes a new envelope.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EnvelopeInput"},{"type":"object","properties":{"send":{"type":"boolean"},"template_id":{"type":"string"},"recipients":{"description":"With template_id: an object from role name to {name, email}. Otherwise an array of recipients."}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"envelope":{"$ref":"#/components/schemas/Envelope"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SendWarning"},"description":"Only with \"send\": true. What the check before sending found. The envelope went out either way."}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"One envelope with its audit trail and email delivery log","description":"Each recipient carries \"progress\": {fields, filled, required_left, ready}, counted as the signer's own screen counts, so a group of radio buttons is one field. \"ready\" is true for someone who signs, has opened the document and has a saved value for everything that is required, but has not pressed Finish: nothing is signed yet, and a reminder to them says that one button is left.\"deliveries\" says what became of every email: \"sent\" means the mail server took it, \"outbox\" that no mail server is set up and nothing was delivered, \"failed\" that the mail server would not take it. A failed email is tried again by the timer with growing gaps, six tries in all over about a day and a half: \"next_try_at\" is when, and a failed email without it is final. The audit trail says the same: \"Sent to recipient\" is only written when the mail server took the email, otherwise \"Not emailed\" or \"Email could not be sent yet\", followed by \"Email sent\" or \"Email could not be sent\".","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"envelope":{"$ref":"#/components/schemas/Envelope"},"removed_at":{"type":"string","format":"date-time","nullable":true,"description":"Set when the sender removed this envelope from their lists after somebody had signed. Only an admin of the account can still open it then; everyone else gets 404. See POST /envelopes/{id}/restore."},"audit":{"type":"array","items":{"$ref":"#/components/schemas/AuditEvent"}},"chain":{"type":"object","properties":{"ok":{"type":"boolean"},"events":{"type":"integer"},"head":{"type":"string"}}},"deliveries":{"type":"array","items":{"type":"object","properties":{"to_email":{"type":"string"},"recipient_id":{"type":"string","nullable":true},"subject":{"type":"string"},"status":{"type":"string","enum":["queued","sent","outbox","failed"]},"error":{"type":"string","nullable":true},"at":{"type":"string","format":"date-time","nullable":true},"tries":{"type":"integer","description":"How often the mail server was tried."},"tried_at":{"type":"string","format":"date-time","nullable":true,"description":"The latest try."},"next_try_at":{"type":"string","format":"date-time","nullable":true,"description":"When a failed email is tried again. Empty once it was sent, and on a failed email that nobody tries again."},"delivered_at":{"type":"string","format":"date-time","nullable":true,"description":"When the mail server of the recipient took it, as the mail provider told us. It does not mean the email was read. Empty on a server that is not told about deliveries."},"bounced_at":{"type":"string","format":"date-time","nullable":true,"description":"When it came back."},"bounce_kind":{"type":"string","enum":["hard","soft"],"nullable":true,"description":"\"hard\": the address does not work. \"soft\": the mail server said to try later; nothing was stopped."},"bounce_reason":{"type":"string","nullable":true,"description":"Why, in plain words, followed by what the mail server said."},"complained_at":{"type":"string","format":"date-time","nullable":true,"description":"When the reader marked it as spam."}}}},"print_problems":{"type":"array","description":"Names and wording that hold a character the signed PDF has no font for. The PDF prints Latin with accents, Greek, Cyrillic, Arabic, Hebrew, Armenian, Georgian, Chinese, Japanese, Korean, Thai, Devanagari and Khmer. Any other character is printed as the mark U+FFFD and listed in the certificate by its Unicode number, never as an empty box. Empty when everything can be printed, and once the signed PDF is stored.","items":{"type":"object","properties":{"where":{"type":"string","description":"Which text, in words: \"The name ...\", \"The subject\", \"A note on page 1\"."},"chars":{"type":"string","description":"The characters that cannot be printed, each once."}}}},"texts":{"type":"array","description":"What became of every text message about this envelope, newest first: a one-time code, the signing link or a reminder. The number is masked and the text itself is not given. A text the provider would not take is tried again like an email, and one the provider refuses for good is final at once.","items":{"type":"object","properties":{"recipient_id":{"type":"string","nullable":true},"kind":{"type":"string","enum":["code","link","reminder"]},"to":{"type":"string","description":"Masked, such as \"+44 *** *** 0123\"."},"status":{"type":"string","enum":["queued","sent","outbox","failed"]},"error":{"type":"string","nullable":true},"at":{"type":"string","format":"date-time","nullable":true},"tries":{"type":"integer"},"tried_at":{"type":"string","format":"date-time","nullable":true},"next_try_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Replace a draft, or correct an envelope that is already out","description":"What the body holds replaces what the envelope holds: \"documents\", \"recipients\" and \"fields\" are full lists, and a list you send replaces the one that was there. A part you leave out altogether (the subject, the message, \"ordered\", the reminder and deadline days, the date format, or one of the three lists) stays as it is. A template can only be changed by the person it belongs to, by an admin, or by whoever its rule lets change it: anyone else on the team gets 403 and can copy it instead, unless its wording is locked. A part of the body that cannot be carried out as it is written answers 400, names the part and saves nothing. It is never dropped, cut short or moved to the nearest allowed value. That goes for a field of a type that does not exist, or for a recipient or a document that is not in the body; a role, a date format or a kind that does not exist; two documents, recipients or fields with the same id; a page the document does not have; a document without its \"file_id\", or with the id of a file that is not in your account; text that is longer than its limit, or sent as a list or an object; a number outside its range; a place or a size on the page (x, y, w, h) that is not a number; a yes or no (\"ordered\", \"readonly\", \"required\") that is not true or false, such as \"false\" in quotes, which would otherwise count as yes; a list that is not a list; and a value on a field that only its signer fills in (a signature, initials, an attachment, a name, an address, a date of signing). Three things are adjusted and not refused: a field that would hang over the edge of its page is moved inside it, a width or height below 0.005 of the page is made 0.005 (and 0 counts as left out, which gives the usual size), and keys this API does not know are not read. A template whose rule says so can also be changed by the members its owner or an admin chose, or by everyone on the team (see /envelopes/{id}/access). An envelope started from a template whose wording is locked keeps, for whoever may not change that template, its documents (the files, their names and order), its fields (where they are, their size, settings and whose they are), the wording the template put in fields and notes, the message, the payment link, and the people on it with what each does and their place in the order: a body that changes one of those answers 403 with \"code\": \"wording_locked\", says what and who can change the template, and saves nothing. Names, email addresses, access codes, notes, checks, reminders, the deadline, the subject and the values of the fields the template left empty can be filled in. GET /envelopes/{id} says so in \"wording_lock\". For a sent envelope this is a correction: no void, no resend, no extra count. Anything can change until a signer, approver or viewer has finished. After that, names, email addresses and the signing order of the people who have not finished can still change, except a name or an address that a full name or email field prints on the pages. What is printed on the documents (the files and their order, every field and whose it is, wording written by the sender, a name or an address printed by a full name or email field, also of someone who only gets a copy, and the date format) and the people who finished themselves (name, email, role, place in the order, or taking them off) can only change if you choose to ask those people to sign again. Their access code and private note can change without that. Without that choice such a call answers 409 with \"code\": \"sign_again\", the names in \"sign_again\" and what would change in \"changes\", and saves nothing. The same call with \"resign\": true is saved: everyone who finished goes back to waiting, is emailed what changed and asked to sign again, their first signature and answers stay on record in the audit trail, the document as they signed it is kept for them to download, the certificate shows both times, and signing again never uses a second signature. A value that a signer typed into their own field is never changed by this call, whatever the body carries for it, and neither is what a signer who has finished left empty or unticked: that is their answer. A line that a signer who has not finished yet emptied stays empty when the body carries your wording as it was; new wording replaces it, and they are told. When a correction changes the signing order, anyone who has the document but is now behind someone who has not finished is told to wait and is asked again when it is their turn. Every correction that changes what a signer sees, their own name included, raises the envelope's content_version, and a signer whose screen still shows an older version cannot finish until it has loaded the new one: the signing page fetches a replaced file again and keeps Finish switched off until its pages are on the screen. The audit trail records what a correction changed, in words. To keep one editor from overwriting another, send the edit_version you got from GET: if the envelope has changed since, the call answers 409 with \"code\": \"stale\", who changed it (\"edited_by\"), when (\"edited_at\") and, when it was not a save, what happened (\"edited_how\"), and saves nothing. A body without edit_version is not checked.","requestBody":{"required":true,"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/EnvelopeInput"},{"type":"object","properties":{"edit_version":{"type":"integer","description":"The edit_version of the copy this body was made from. Optional. With it, the call is refused (409, \"code\": \"stale\") when the envelope has changed since: a save, a quick correction of one recipient, a signer who passed the document on or fixed their name, or sending."},"resign":{"type":"boolean","description":"Sent envelopes only. true means: save this even though it touches what finished people signed, and ask them to sign again."}}}]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"envelope":{"$ref":"#/components/schemas/Envelope"}}}}}},"409":{"description":"Not saved. \"code\" says why: \"sign_again\" (the change touches what finished people signed, see \"sign_again\" and \"changes\") or \"stale\" (the envelope changed after the edit_version you sent, see \"edited_by\", \"edited_at\" and \"edited_how\").","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"code":{"type":"string","enum":["sign_again","stale"]},"sign_again":{"type":"array","items":{"type":"string"}},"changes":{"type":"array","items":{"type":"string"}},"edit_version":{"type":"integer"},"edited_by":{"type":"string"},"edited_at":{"type":"string","format":"date-time","nullable":true},"edited_how":{"type":"string","nullable":true,"description":"What the newer change was when it was not a save: it finishes the sentence that starts with edited_by, for example \"passed this document on to Mary Deputy\"."}}}]}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Move to a folder","description":"A template can only be moved by someone who may change it: the person it belongs to, an admin, or whoever its rule lets change it (403 otherwise).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"folder":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a draft, a template or a closed envelope, or take a completed envelope out of your account","description":"A draft, a template or a voided, declined or expired envelope that nobody had signed is deleted for good, with its audit trail, our copies of its emails and the files signers attached. A completed envelope, and any other envelope on which somebody has already signed or approved, is not only the sender's: deleting it removes it from the sender's lists, search, export and reports (it then answers 404 here for everyone but the admins of the account), and every recipient's signing link, download and list of documents sent to them keep working. The answer then has \"kept_for_recipients\": true. The admins of the account still find it with GET /envelopes?box=removed, can open and download it, and can put it back with POST /envelopes/{id}/restore; nothing else can be done to it until then. It is removed for good when the account is closed. An envelope that is out for signature must be voided first (400). A template can only be deleted by the person it belongs to or by an admin (403), also when its rule lets other members change it.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"kept_for_recipients":{"type":"boolean","description":"true when an envelope somebody had signed was taken out of the sender's account and its recipients keep their copy."}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/send":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Send a draft","description":"The answer carries \"warnings\": what the check before sending found (see SendWarning). It is a list to read. The envelope has gone out whether the list is empty or not, and each finding is also written to the audit trail. On a server that is told about bounces: when an address on it is one at which an email of this account came back for good in the last 30 days, the call answers 409 with \"code\": \"bounced_address\" and \"bounced\": [{email, bounced_at, reason}], and nothing is sent. Repeat it with {\"send_anyway\": true} to send all the same; the audit trail then says you were warned. The same holds for POST /envelopes with \"send\": true and for POST /bulk. A public form is never held back this way. Sending, and correcting an envelope that is out (PUT /envelopes/{id}), answer 400 when two fields of the same recipient on one page cover each other by more than 60 percent of the smaller one and at least one of them is filled in by the recipient: on a phone only the top one can be tapped. The error names the recipient and the page; move or remove one and send again.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"send_anyway":{"type":"boolean","default":false}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"envelope":{"$ref":"#/components/schemas/Envelope"},"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SendWarning"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/warnings":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The check before sending, for a draft, a template or an envelope","description":"Looks at the subject, the document names and the text read from the documents for words that name a kind of document which often needs ink on paper, a witness, a notary or a qualified signature: a will, a trust deed, a power of attorney, a sale of land or a long lease, a fixed-term employment contract or a notice of termination, a deed that needs a witness. Sign&Grow makes simple electronic signatures only. Nothing here is legal advice and nothing is ever refused because of it: \"blocks\" is always false. An empty list means only that none of the words was found. The words are listed on the help page.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"warnings":{"type":"array","items":{"$ref":"#/components/schemas/SendWarning"}},"blocks":{"type":"boolean","enum":[false]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/pay-link":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The link to your own payment page, shown to signers after Finish","description":"pay_link is null when there is none. \"may\" says whether this account may show one now, and \"why\" says in a sentence why not: an account needs a payment for the plan or a top-up that is at least 14 days old and was not refunded or disputed, or to be cleared by a person, and a pause or a card dispute takes every link of the account off the screens until it is over. \"people\" lists each person who signs, with when they were first shown the link and when they first pressed it. Whether anyone paid is never known here: your payment provider knows.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"pay_link":{"type":"object","nullable":true,"properties":{"url":{"type":"string"},"host":{"type":"string"},"kind":{"type":"string"},"label":{"type":"string"}}},"may":{"type":"boolean"},"why":{"type":"string","nullable":true},"kinds":{"type":"object","additionalProperties":{"type":"string"}},"people":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"shown_at":{"type":"string","nullable":true},"opened_at":{"type":"string","nullable":true}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Set, change or remove the link to your own payment page","description":"Sign&Grow takes no part in the payment. The address is shown, in full and with the sender's name, to each person who signs, after they press Finish, while the envelope is out or completed; it is never put in an email. It must start with https:// and name a site on the public internet: no IP address, no port, no name or password before an @, no spaces or invisible characters, at most 500 characters, and not this server. An empty \"url\" removes it, which is always allowed. Adding or changing it is refused with 403 for an account that may not show one (see GET), and with 409 once the envelope is completed, voided, declined or expired. A template's link goes with every envelope made from it, including bulk sends and public forms. On an envelope, every change is written to the audit trail, and so is the first time each person is shown it and presses it. Saving it changes nothing on the pages and emails nobody. On a template, only someone who may change the template can change it (403). On an envelope started from a template whose wording is locked, it cannot be changed by someone who may not change that template (403, \"code\": \"wording_locked\").","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"The address of your own payment page, or \"\" to remove the link."},"kind":{"type":"string","enum":["deposit","retainer","fee","payment"],"description":"What the button says: Pay the deposit, Pay the retainer, Pay the fee, Make the payment. Left out, it stays what it was, or deposit."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"pay_link":{"type":"object","nullable":true,"properties":{"url":{"type":"string"},"host":{"type":"string"},"kind":{"type":"string"},"label":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/void":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Void an envelope that is out","description":"Never refused because of a pause. Everyone who has the document is emailed that it was voided, with the reason. Where the fake-notice check applies to the account (see the description at the top), and for every account while it is paused, the reason is read together with the subject it is printed under: 422 when the two read like a fake payment notice, and a plain reason then voids it. While the account is paused the email goes without the reason.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/remind":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Remind everyone whose turn it is, or one recipient","description":"Refused with 403 while the account is paused, and with 422 while the envelope reads like a fake payment notice or goes out under a name that reads like a well-known brand. A recipient with \"link_by_sender\" has no address: naming one is refused with 400, and reminding everyone lists them in \"not_reminded\" so you can send their link again yourself.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"recipient_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reminded":{"type":"integer"},"not_reminded":{"type":"array","items":{"type":"object","properties":{"recipient_id":{"type":"string"},"name":{"type":"string"},"why":{"type":"string","enum":["email_bounced","marked_as_spam","link_by_sender"]}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/correct":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Fix one recipient's name, email or access code","description":"For someone who has not finished, while the envelope is out. The access code alone can still be changed for someone who has finished, and once the envelope is completed, voided, declined or expired: send \"access_code\" with the name and email as they are, or leave them out. Anything else there answers 400 and changes nothing. That is how someone whose code froze gets back to the copy of what they signed. A new name at the same address that is not the old one in another spelling (a word swapped for another, not a letter or two) is another person: the link stays, because it went to that inbox, but the signature, initials, answers and agreement of the person before are cleared. A new email address is a new person being emailed: it is refused while the account is paused (403) and counts towards the daily limit (429), and nothing the first person filled in goes with it. A new person (a new address, or a name at the same address that is not the old one in another spelling) never signs on the signature the first person used or had held: theirs is their own, also after \"sign again\", and when none is free the call answers 402 and changes nothing. The same holds for PUT /envelopes/{id} and for a signer passing the document on. A new access code needs at least 4 characters (400) and unfreezes a code that was frozen after too many wrong tries. Sending the same code again for a code that is frozen answers 400 and changes nothing, because it would not let anyone in. A new name raises the envelope's content_version, so a signing screen that still shows the old name cannot finish until it has loaded the new one, and whoever has the document and sees the name is emailed. Where a full name or email field prints this person's name or address on the pages and someone has already finished, the call answers 409 with \"code\": \"sign_again\" and changes nothing: make the change with PUT /envelopes/{id} and \"resign\": true, so the people who finished are asked to sign again. Every correction counts up the envelope's edit_version. \"verify\", \"phone\" and \"text_link\" work as on a recipient: changing the check or the number makes the person pass the check again, lets a number be texted again after someone said it was not theirs, and writes \"Check corrected\" to the audit trail with the numbers masked. When the email address changes to another person's and a text is still asked for, their phone has to be in the same call (400 otherwise). The call does all of it or none.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient_id"],"properties":{"recipient_id":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"access_code":{"type":"string"},"verify":{"type":"string","enum":["none","email_code","sms_code"]},"phone":{"type":"string"},"text_link":{"type":"boolean"},"number_confirmed":{"type":"boolean","description":"After someone using the link said the mobile number is not theirs, no code and no text goes to it. Send true when you have checked with the person, a way you trust, that the number is right after all: codes go to the same number again, and the audit trail says you confirmed it. Only ever sent on purpose: sending the recipient back unchanged does not lift the stop."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/extend":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Push the deadline out, or reopen an expired envelope","description":"More time for an envelope that is still out emails nobody and is always allowed, also while the account is paused. Reopening an expired envelope emails everyone who still has to sign, so it is refused with 403 while the account is paused and with 422 while the envelope reads like a fake payment notice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer","minimum":1,"maximum":365,"default":30}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"expires_at":{"type":"string","format":"date-time","nullable":true}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/restore":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Put back an envelope its sender removed from their lists","description":"For admins of the account, and for their API keys of either scope (403 for a member; 404 for an envelope that is not in the account). An envelope its sender deleted after somebody had signed is in nobody's lists, search, export or reports, but it is still stored and its recipients still have it. This makes it an ordinary envelope again for its sender and for the admins, and writes \"Put back in the sender's lists\" with who did it to the audit trail. Asking again for one that is back already changes nothing and writes nothing.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"envelope":{"$ref":"#/components/schemas/Envelope"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/clone":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Copy as a new draft or template","description":"A copy of a template, or a template made from an envelope that was started from one, has the same rule as that template: who can use it, who can change it, the chosen members and the lock. A copy of a template whose wording is locked, made by someone who may not change it, belongs to the person the template belongs to, so a copy is never a way round the lock: the answer then says so in \"belongs_to\". An envelope copied from one whose wording is locked is locked in the same way.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"kind":{"type":"string","enum":["envelope","template"]}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"belongs_to":{"type":"string","description":"Only when the copy belongs to someone else: their name."},"locked":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/access":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Who can use and change a template","description":"Templates only (404 for an envelope). \"use\": \"team\" (everyone on the team, the default), \"admins\" (admins only) or \"chosen\" (chosen members). \"change\": \"owner\" (the person it belongs to and admins, the default), \"chosen\" (chosen members as well) or \"team\" (everyone on the team). \"locked\": true when its wording is locked (see PUT /envelopes/{id}). Admins and the owner of the account can always use and change every template, and whoever may change a template may use it. \"may_use\", \"may_change\", \"may_delete\" and \"may_set\" say what the caller may do. The person it belongs to and admins also get \"members\": everyone on the team, with \"chosen\" and \"can_change\", and \"always\" for those who can always use and change it. A template the caller may not use answers 403 with \"code\": \"template_not_for_you\" and who to ask, here and wherever the template is read, used, sent in bulk, copied or published as a public form.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access":{"$ref":"#/components/schemas/TemplateAccess"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"put":{"summary":"Set who can use and change a template, and lock its wording","description":"Only for the person the template belongs to and for admins (403 for everyone else, also for chosen members who may change it). Whatever you leave out stays as it is. \"members\" is the whole list of chosen members and replaces the one before; each must be on your team (400 otherwise). \"change\": \"team\" needs \"use\": \"team\" (400). Locking applies to envelopes started from the template from then on; unlocking it, or letting someone change it, frees the envelopes already started too. Every change is written to the template's history (the audit list of GET /envelopes/{id}) with the rule before and after.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"use":{"type":"string","enum":["team","admins","chosen"]},"change":{"type":"string","enum":["owner","chosen","team"]},"locked":{"type":"boolean"},"members":{"type":"array","items":{"type":"object","required":["id"],"properties":{"id":{"type":"string","description":"A user id, from this call or GET /account/members."},"can_change":{"type":"boolean","description":"Also may change it, when \"change\" is \"chosen\"."}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"access":{"$ref":"#/components/schemas/TemplateAccess"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/recipient-view":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Get one recipient's signing link, for embedded signing","description":"Send the person to this URL in a new tab or by redirect. It cannot be shown inside an iframe. Treat it like a password. Asking again returns the same link, until a corrected address or a reassignment replaces it. The audit trail, which is printed on the certificate, records \"Signing link issued\" at most once in 24 hours for each link, however often you ask.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient_id"],"properties":{"recipient_id":{"type":"string"},"member_id":{"type":"string","description":"For a group recipient that nobody has taken on: which member's link (members[].id). Every member has a link of their own, so it is known who acted. Not needed once someone has taken it on: the recipient's link is then theirs."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/recipients/{rid}/release":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"rid","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Give a group's document back to the whole group","description":"For a group recipient that one member has taken on and not finished: the answer to a colleague who asked to take over, or to someone who is away. What that person filled in is cleared, every member's own link opens the document again and they are emailed. Answers 409 when nobody has it or it is already finished.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/groups":{"get":{"summary":"The signing groups of the account","description":"Everyone on the team can read them and put them on an envelope or template (\"group_id\" on a recipient). \"may_change\" says whether you can change them: that is for admins.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"}},"min_members":{"type":"integer"},"max_members":{"type":"integer"},"may_change":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Make a signing group (admins)","description":"Refused with 400, and nothing saved, for a member without a name or a valid address, an address that is there twice, or too few or too many members. A name the account already has answers 409.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"$ref":"#/components/schemas/Group"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/groups/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"put":{"summary":"Replace the name and the members of a group (admins)","description":"Drafts and templates that name it follow it. Envelopes already sent keep the members they went out with: change those with PUT /envelopes/{id} and \"members\".","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"group":{"$ref":"#/components/schemas/Group"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a group (admins)","description":"Envelopes already sent to it are not affected. A draft or template that names it cannot be sent until that recipient is changed.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/download":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The signed PDF with its certificate, or a preview while in progress","description":"For an envelope that was voided, declined or ran out of time, the copy opens with a page that says it was not completed by everyone and why, and every page carries that at its foot and in large letters across it, so the signatures collected by then never pass for a signed document. It has no certificate.","responses":{"200":{"description":"A PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/evidence":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The evidence pack: one ZIP with what a sender keeps outside Sign&Grow","description":"signed.pdf (the stored signed file, byte for byte) and certificate.pdf (its certificate alone), or for an envelope that is not completed the document as it stands, marked as such; audit-trail.txt and audit-trail.json (every line with prev_hash and hash, the stored browser string, the people on the envelope, and the chain as checked now, with how each hash is made); emails/ (a copy of every email stored about the envelope as HTML, with signing links and security codes taken out because they would still open the document, and emails/index.csv with what became of each and the SHA-256 of each as stored); consent.txt (the wording each person agreed to, by the version their audit line names); README.txt. A snapshot of the moment it is made. 400 for a draft.","responses":{"200":{"description":"A ZIP file","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/comments":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The questions and comments on an envelope, every thread, with who has not been answered","description":"For the sender and the admins of the account, and for their API keys of either scope. Every thread is listed, the private ones too: the sender's side is in all of them. A person on the envelope reads only the threads for everyone and their own private ones, on their signing page. \"waiting\" lists the threads whose last word is from someone on the envelope. Readable for as long as the envelope is kept, also after it is completed or closed. Comments are not printed on the document and are not part of what is signed. The record of the document says that a comment was written, by whom and when, never what it says. 409 for a draft.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"threads":{"type":"array","items":{"$ref":"#/components/schemas/CommentThread"}},"waiting":{"type":"array","items":{"type":"object","properties":{"thread_id":{"type":"string"},"name":{"type":"string"}}}},"may_write":{"type":"boolean","description":"false once the envelope is no longer out: the threads can be read, not added to."},"people":{"type":"array","description":"Who can be written to privately now: whoever can read the document. Not someone whose turn has not come, and not a group nobody has taken on yet.","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Write a comment, or answer in a thread, from the sender's side","description":"Only while the envelope is out (409 \"read_only\" after). Send \"thread_id\" to answer in a thread. To start one, \"for\" is required and never guessed: \"everyone\", or the id of one person on the envelope to write to them alone (400 without it). \"pin\" puts it on a place in a document. Up to 2000 characters (400 above, with the count; nothing is cut short), 50 comments for each person on the sender's side on one envelope and 30 in 10 minutes (429). It is emailed to the person a private thread is with, or in a thread for everyone, to each person on the envelope who wrote in it, at most once every 10 minutes for each person: a newer one waits and goes with the next. A new thread for everyone emails nobody. The words are shown on our signing page and emailed in the sender's name, so they are read with the envelope like any other email: 422 when they read like a fake payment notice (see the description at the top), and while sending is paused nothing is emailed: the comment is saved and shown, and its email goes out by itself once the pause is lifted (\"message\" says so). The audit trail gets a line that a comment was written, by whom and when, never its words. The \"comment.created\" webhook fires.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"text":{"type":"string","maxLength":2000},"thread_id":{"type":"string"},"for":{"type":"string","description":"\"everyone\", or a recipient id. Only for a new thread."},"pin":{"type":"object","properties":{"document_id":{"type":"string"},"page":{"type":"integer","minimum":0},"x":{"type":"number","minimum":0,"maximum":1},"y":{"type":"number","minimum":0,"maximum":1}},"description":"Only for a new thread. x and y are fractions of the page from its top left corner, both or neither."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"thread_id":{"type":"string"},"comment_id":{"type":"string"},"told":{"type":"array","items":{"type":"object"}},"message":{"type":"string","description":"What happened, in words: who sees it and who is emailed."},"threads":{"type":"array","items":{"$ref":"#/components/schemas/CommentThread"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/comments/{thread}/settle":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"thread","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Mark a thread as settled, or open it again","description":"Only while the envelope is out. Send {\"settled\": false} to open it again; leave the body out to settle it. A new comment in a settled thread opens it again by itself. The audit trail records who did it.","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"settled":{"type":"boolean","default":true}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/powerforms":{"get":{"summary":"List the public forms (PowerForms) of the account","description":"Each form is a public link that anyone can open to fill in and sign a template. A form on a template the caller may not use is not listed, and \"may_change\" says whether the caller may pause, change or delete it: whoever may change its template. Making one (POST /powerforms) is for them as well. There is no call that returns a QR code: the app draws the code in the browser from \"url\", and any QR tool can do the same.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"powerforms":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"slug":{"type":"string"},"url":{"type":"string","format":"uri","description":"The public address of the form, built from APP_URL like every link in an email. Whoever has it can open the form, fill it in and sign. It stops working while the form is paused and for good when it is deleted."},"active":{"type":"integer","description":"0 while the form is paused."},"shared_device":{"type":"boolean"},"signed":{"type":"integer","description":"How many people finished."},"open":{"type":"integer","description":"How many are filling it in now."},"created_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bulk":{"get":{"summary":"List bulk send batches","description":"A member gets the batches they sent, an admin gets every batch in the account. When a member is removed from the team, their batches pass to the same person as their envelopes.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"batches":{"type":"array","items":{"type":"object"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Send a template to many people (up to 500 rows)","description":"The call answers when every row has been tried, so it takes as long as the mail server needs for the whole list. Every row is written to the batch before anything is sent, and GET /bulk/{id} shows how far it has got. Send an Idempotency-Key, so that a call that timed out can be repeated without anyone getting a second copy.","parameters":[{"name":"Idempotency-Key","in":"header","description":"Any string of up to 200 characters that you make up for this one call. Repeating the call with the same key and the same body never makes a second batch. If the first call has finished, the repeat answers 200 with the same result. If the first call is still sending, the repeat answers 202 at once with the same batch id and what has gone out so far. If the server stopped half way, the repeat sends the rows that had not gone out and answers 200 when it is done. Rows that were tried and could not be sent are not tried again. The one envelope that was being sent at the moment the server stopped is not emailed again: GET /envelopes/{id} shows whether its email left, and POST /envelopes/{id}/remind sends it if it did not. A key belongs to whoever sent it, as on POST /envelopes, and the same key with a different body answers 409 and sends nothing. Without the header every call makes a new batch.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template_id","rows"],"properties":{"template_id":{"type":"string"},"name":{"type":"string"},"send_anyway":{"type":"boolean","default":false,"description":"Send although an address in the list bounced for good lately. Without it such a batch answers 409 with \"code\": \"bounced_address\", and nothing is sent to anyone. POST /bulk/check lists those addresses in \"bounced\" beforehand."},"rows":{"type":"array","items":{"type":"object","description":"From role name to {name, email}, and \"phone\" where the template checks that role with a code by text message or texts them the link. A row without a phone the template needs, or with one that is not a full international number, refuses the whole batch with 400 before anything is sent, and so does a batch that would send more text messages than the account may today (429). A row may also carry \"fields\": an object from the label (or id) of a template field to a value, like {\"Plan\": \"Gold\", \"Seats\": \"3\"}. It fills that field like a value you prefilled, so the signer starts with it and a \"show_when\" that depends on it shows or hides from the first look. A checkbox takes yes, 1 or true; a radio group is named by its group and takes the label of the button to choose. A label that names no field or two fields, a choice a dropdown does not have, a number that does not read as one, a calculated field, a field only its signer fills in and the template's own fixed wording refuse the whole batch with 400, naming the row, before anything is sent.","example":{"Client":{"name":"Ada Lovelace","email":"ada@example.org"},"fields":{"Plan":"Gold"}},"additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"},"phone":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"Every row has been tried.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkResult"}}}},"202":{"description":"A repeat of a call that is still sending: the same batch, with what has gone out so far.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkResult"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bulk/check":{"post":{"summary":"What a bulk send would hold and cost, before it is sent","description":"Takes the body of POST /bulk and sends nothing. Each person who signs uses one signature, and a batch only goes out when all of its signatures are in the balance, so this says how many the list holds, how many are free to send with, how many are missing and what the missing ones cost on the account's plan. The count is the one POST /bulk is held to. \"refusal\" is what POST /bulk would answer because of a pause, the filter for fake payment notices or the daily limit on people newly emailed, in the same words. Rows are not checked for missing names or addresses here: POST /bulk does that.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["template_id","rows"],"properties":{"template_id":{"type":"string"},"rows":{"type":"array","items":{"type":"object","description":"From role name to {name, email}, as for POST /bulk.","additionalProperties":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string"}}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"counted":{"type":"boolean","description":"false when no payment provider is connected. Nothing is counted then and every batch goes out."},"rows":{"type":"integer"},"signers_per_row":{"type":"integer","description":"People in the template who sign and are not the sender signing under their own name."},"need":{"type":"integer","description":"Signatures the batch holds: signers_per_row times rows."},"have":{"type":"integer","description":"Signatures free to send with now: the balance without those held for envelopes that are out."},"short":{"type":"integer","description":"How many are missing. The batch only goes out when this is 0."},"plan":{"type":"string"},"cost":{"type":"object","nullable":true,"description":"What the missing signatures cost in US dollars, or null when none are missing. On the monthly plan it is a top-up. On the free plan a top-up needs the monthly plan first, so it is one monthly payment, which brings plan_signatures, plus a top-up for the rest.","properties":{"usd":{"type":"number"},"plan_usd":{"type":"number"},"plan_signatures":{"type":"integer"},"top_up":{"type":"integer"},"top_up_usd":{"type":"number"}}},"refusal":{"type":"object","nullable":true,"properties":{"status":{"type":"integer","description":"403 paused, 422 reads like a fake payment notice, 429 over the daily limit."},"message":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bulk/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"One batch with every envelope and recipient status, and what happened to every row","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"batch":{"type":"object"},"envelopes":{"type":"array","items":{"$ref":"#/components/schemas/Envelope"}},"sending":{"type":"boolean","description":"true while a call is sending this batch right now."},"rows":{"type":"array","description":"One entry per row of the request. Empty for batches sent before rows were recorded.","items":{"type":"object","properties":{"position":{"type":"integer","description":"Place in the list that was sent. The first row is 0."},"status":{"type":"string","enum":["sent","failed","pending"]},"envelope_id":{"type":"string","nullable":true},"sent_at":{"type":"string","format":"date-time","nullable":true},"error":{"type":"string","nullable":true,"description":"Why the row could not be sent."},"row":{"type":"object","nullable":true,"description":"The row as it was submitted. Shown until the row is sent; after that its envelope has the names and addresses."}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bulk/{id}/remind":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Remind everyone in the batch who has not finished","description":"Goes through the envelopes that are out for signature one at a time. An envelope that is finished or closed while the call is at work is passed over and nobody on it is reminded.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"reminded":{"type":"integer","description":"How many people were sent a reminder."}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/bulk/{id}/void":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Void everything in the batch that is still open","description":"Goes through the envelopes that are out for signature one at a time and emails the people on each. An envelope that is completed, declined or voided while the call is at work is left as it is and counted in \"skipped\", and the rest are still voided. The call can be repeated: it only ever touches envelopes that are still out for signature.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["reason"],"properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"voided":{"type":"integer","description":"Envelopes this call voided."},"skipped":{"type":"integer","description":"Envelopes that were out for signature when the call began and had closed by the time their turn came. They were not changed."}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/print-check":{"post":{"summary":"Ask whether text can be printed on the signed PDF, before it is saved or sent","description":"For each text that holds a character the signed PDF has no font for, the answer says where and which characters. See \"print_problems\" on GET /envelopes/{id} for the scripts that print. Nothing is saved by asking.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["texts"],"properties":{"texts":{"type":"array","items":{"type":"object","properties":{"where":{"type":"string","description":"Your own label for this text. It comes back with the answer."},"text":{"type":"string"}}}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"problems":{"type":"array","items":{"type":"object","properties":{"where":{"type":"string"},"chars":{"type":"string"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/export":{"get":{"summary":"A ZIP of signed PDFs, audit trails and a CSV index","description":"Everything the caller can see: their own envelopes for a member, the whole account for an admin. A completed envelope its sender deleted is not in it.","parameters":[{"name":"ids","in":"query","description":"Comma separated envelope ids. Leave out for everything.","schema":{"type":"string"}},{"name":"bulk","in":"query","description":"A bulk batch id, to export just that batch.","schema":{"type":"string"}}],"responses":{"200":{"description":"A ZIP file","content":{"application/zip":{"schema":{"type":"string","format":"binary"}}}}}}},"/reports/summary":{"get":{"summary":"Counts, completion time and paper saved","description":"Counts what the caller can see in their lists, so a completed envelope its sender deleted is not counted.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api-keys":{"get":{"summary":"List API keys: your own, or every key in the account for an admin","description":"Shows the name, scope, owner and last use of each key, never the key itself. Creating and revoking keys is done by a person in Settings, not with a key.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"$ref":"#/components/schemas/ApiKey"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks":{"get":{"summary":"Webhooks and their delivery log (account admins)","description":"Deliveries come newest first, 30 at a time. A key with the \"send\" scope gets \"secret\": null.","parameters":[{"name":"webhook","in":"query","description":"A webhook id, to list the deliveries of that webhook only.","schema":{"type":"string"}},{"name":"before","in":"query","description":"The next_before of the page before, to go further back.","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"events":{"type":"array","items":{"type":"string"}},"webhooks":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"string"},"active":{"type":"integer"},"secret":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time","nullable":true}}}},"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next_before":{"type":"integer","nullable":true,"description":"null when there is nothing older."}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Add a webhook (needs a key with the \"admin\" scope; up to 20 per account)","description":"The address must use https and be on the public internet. Deliveries go to the address the name pointed to when it was checked, time out after 10 seconds, and do not follow redirects.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["envelope.sent","envelope.completed","envelope.declined","envelope.voided","envelope.expired","envelope.corrected","envelope.updated","recipient.viewed","recipient.completed","comment.created"]},"description":"Leave out to get every event."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/envelopes/{id}/try-again":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Email a recipient again after an email to them came back","description":"For a recipient with \"bounced_at\", when you know the address works now. The mark goes, reminders to the address are on again, it comes off the account's list of addresses that bounced, and the request is emailed again at once. \"delivery\" says what became of that email: \"sent\" (the mail server took it), \"outbox\" (no mail server is set up), \"failed\" (the mail server would not take it yet; it is tried again), \"waiting\" (it is not their turn yet; the email goes out when it is), \"held\" (held back, and you were told why). Answers 409 when nothing came back from them, when the envelope is no longer out, and for someone who marked our email as spam (\"code\": \"marked_as_spam\"), which only that person can undo. Fires envelope.updated with \"change\": \"email_tried_again\".","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["recipient_id"],"properties":{"recipient_id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"delivery":{"type":"string","enum":["sent","outbox","failed","waiting","held"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"delete":{"summary":"Remove a webhook (needs a key with the \"admin\" scope)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhooks/deliveries/{id}/redeliver":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Send a past delivery again, exactly as it was (needs a key with the \"admin\" scope)","description":"Works for the latest 200 deliveries of each webhook. Answers 409 while the delivery is still being tried.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account/invites":{"post":{"summary":"Invite someone to the team by email (needs a key with the \"admin\" scope)","description":"An invitation is an email to an address you type, printed under your name and the account's name, so it has the rules an envelope has. 403 until the inviter's email address is confirmed, and while sending is paused on the account (with the reason). 422 when one of the two names reads like a well-known brand or like a fake payment notice, until the account has a payment that is at least 14 days old and was not refunded or disputed. 429 after 20 different people in 24 hours: asking the same person again does not count, cancelling an invitation gives nothing back, and a person on our team can lift the limit by clearing the account.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string"},"role":{"type":"string","enum":["member","admin"],"default":"member"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/auth/providers":{"get":{"summary":"Which providers people can sign in with on this server, next to email and password","description":"Google and Microsoft, each only when the operator of the server has set it up. Empty when neither is. Signing in itself happens in a browser, for a person: the app sends them to the provider and back, and no API key takes part in it.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"providers":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","enum":["google","microsoft"]},"name":{"type":"string"}}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/verify":{"post":{"summary":"Check whether a PDF is, byte for byte, a completed document we hold","description":"\"match\" true means the file is the one stored when the last person finished, so it is unchanged since. It does not show who was behind each signature. The answer then carries the envelope (with \"disputed_at\" when a person named on it said they did not sign it, or that it was not them), its signers with shortened addresses, and the state of its audit trail. \"match\" false with \"deleted\" set: the file is the signed PDF of a completed document whose sender has deleted it with their account; only its envelope id, its day (\"completed_at\"), when it was deleted and until when we keep knowing it (\"kept_until\", a year) are left. \"match\" false with \"deleted\": null: no completed document we hold or remember has this fingerprint. 429 after 60 files an hour from one connection.","security":[],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"match":{"type":"boolean"},"hash":{"type":"string"},"deleted":{"type":"object","nullable":true,"properties":{"envelope_id":{"type":"string"},"completed_at":{"type":"string"},"deleted_at":{"type":"string"},"kept_until":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/verify/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Look an envelope up by the ID printed at the foot of every page","description":"For the holder of a printed or scanned copy. An ID is not a secret, so the answer never holds a name, an address, the title, the sender or the account: \"status\" (completed, sent, voided, declined, expired, or deleted for a completed one whose sender deleted it in the last year), \"sent_at\", \"completed_at\", \"closed_at\", \"pages\" ({documents, signed_file}), \"signers\" and \"signed\" (people asked to sign, and how many did), \"approvers\", \"sha256\" (the fingerprint of the signed file, to compare a file with), \"disputed_at\" and \"disputes\" (how many people named on it dispute it). 400 for something that is not an envelope ID, 404 for a draft, a template or an ID we do not hold, 429 after 60 lookups an hour from one connection.","security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"id":{"type":"string"},"status":{"type":"string"},"completed_at":{"type":"string","nullable":true},"closed_at":{"type":"string","nullable":true},"pages":{"type":"object","properties":{"documents":{"type":"integer"},"signed_file":{"type":"integer","nullable":true}}},"signers":{"type":"integer"},"signed":{"type":"integer"},"sha256":{"type":"string","nullable":true},"disputed_at":{"type":"string","nullable":true},"disputes":{"type":"integer"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/check/dispute":{"post":{"summary":"\"I did not sign this, or this was not me\", with the security code of an email we sent","description":"For something signed, approved or declined in that person's name, also on a completed document. The envelope is marked as disputed (\"disputed_at\" wherever it is shown), the audit trail gets a \"Disputed\" line that names who said it as far as we know (the holder of that email), the sender is told without what was written, and the people who run the service are told with it. Nothing is changed or deleted. Saying it again answers \"already\": true and does nothing. 409 with \"code\": \"nothing_signed\" when nothing has been done in that person's name yet, or they only got a copy; 404 for a code that no longer stands for anyone on a document; 429 after 10 an hour from one connection.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"detail":{"type":"string","description":"Up to 2000 characters, for the people who run the service only."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"already":{"type":"boolean"},"disputed_at":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sign/{token}/witness":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"The signer names their witness","description":"With the signing link of a person whose witness has \"named_by_signer\": before they finish (their Finish answers 400 with \"code\": \"witness_needed\" until then), and after a witness said they were not there. The witness is emailed straight after the signer has signed, or at once when they already have. Up to 4 names for one witness place. Refused with 400 for the signer's own name or a person who signs the document too, 409 when the sender chose the witness or the witness was already asked (ask the sender), 403 when the account may not email a new person now (the words say only that), 429 after too many names. Each name counts towards the daily limit on new people, and for the visitor of a public form towards that form's own limit. Written to the audit trail as \"Witness named\".","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"witness":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"state":{"type":"string","enum":["open","waiting","asked","absent","done"]},"named_by_signer":{"type":"boolean"},"may_name":{"type":"boolean"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sign/{token}/witness-statement":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"The witness ticks their statement","description":"With the witness's own link, once the person they witness has signed. Send the statement exactly as GET /sign/{token} gave it in recipient.witness_of.statement: \"I was physically present and saw {signer} sign this document on {date}.\" A different text answers 409 with \"code\": \"changed\" and the current one. Their Finish answers 400 with \"code\": \"statement_needed\" until it is ticked. Written to the audit trail as \"Witness statement\" with the words, and printed on the certificate. Sign&Grow records the statement. It cannot check it.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["statement"],"properties":{"statement":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"said":{"type":"boolean"},"statement":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sign/{token}/not-present":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"\"I was not there\"","description":"With the witness's own link, in place of witnessing. Nothing is signed. The signer and the sender are emailed, the audit trail gets \"Witness was not there\", and the envelope stays out, unwitnessed, until another witness has signed. The signer may then name another witness (POST /sign/{token}/witness with their own link). A witness cannot decline or pass on the document: those answer 400 and point here. Saying it twice answers 409.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","description":"Up to 500 characters, passed on to the signer and the sender."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sign/{token}/dispute":{"parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"The same from the signing link","description":"As POST /public/check/dispute, with the link instead of the code. No access code or one-time code is asked for first.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"already":{"type":"boolean"},"disputed_at":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/check":{"post":{"summary":"Check the security code from a signing email","description":"A code from an email whose link was replaced afterwards (the sender corrected the address or the role, the signer passed the document on, or the person was taken off) is still genuine: the answer has \"replaced\": true and \"why\", and no link to open.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"genuine":{"type":"boolean"},"replaced":{"type":"boolean","description":"true when the email was genuine but its link no longer works."},"why":{"type":"string","enum":["address","role","handed","removed"]}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwraps":{"get":{"summary":"Click-to-agree terms of the account (owner and admins)","description":"Each with its state (\"draft\", \"live\", \"closed\" by the team, or \"stopped\" with \"why\": the account is paused or closing, or the terms read like a fake payment notice while the account has not earned trust), its public page and how often it was accepted. \"usage\" is the account's count this month against the limit of this server (1000), over every agreement. An acceptance is not a signature and costs none.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Start new terms as a draft (owner and admins)","description":"Nothing is shown to anyone until it is published. Every agreement gets a page at /agree/{slug} and a key of its own for the links its website signs.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["text","pdf"]},"text":{"type":"string","maxLength":100000,"description":"Plain text. A line starting with \"# \" is a heading (\"## \" a smaller one), \"- \" or \"* \" a list item, \"1. \" a numbered one, **two stars** make words bold, an empty line starts a paragraph. Nothing else is read: no links, no HTML."},"file_id":{"type":"string","nullable":true,"description":"A PDF uploaded with POST /files."},"checkbox":{"type":"string","maxLength":200,"description":"The words next to the tick box. Empty for the default."},"button":{"type":"string","maxLength":200},"scroll":{"type":"boolean","description":"The button works only after the terms were scrolled to the end, checked by the visitor's browser."},"signed_only":{"type":"boolean","description":"Only people the website names in a signed link can accept. Takes effect at once; not a version."}},"required":["name"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwraps/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"One agreement: its draft, versions, key, snippets and who has to accept again (owner and admins)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Change the draft or a setting (owner and admins)","description":"Only what the call names changes. The draft is shown to nobody until it is published. \"active\": false closes the page (the records stay); true opens it again. Yes and no are true and false, never in quotes.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":120},"format":{"type":"string","enum":["text","pdf"]},"text":{"type":"string","maxLength":100000,"description":"Plain text. A line starting with \"# \" is a heading (\"## \" a smaller one), \"- \" or \"* \" a list item, \"1. \" a numbered one, **two stars** make words bold, an empty line starts a paragraph. Nothing else is read: no links, no HTML."},"file_id":{"type":"string","nullable":true,"description":"A PDF uploaded with POST /files."},"checkbox":{"type":"string","maxLength":200,"description":"The words next to the tick box. Empty for the default."},"button":{"type":"string","maxLength":200},"scroll":{"type":"boolean","description":"The button works only after the terms were scrolled to the end, checked by the visitor's browser."},"signed_only":{"type":"boolean","description":"Only people the website names in a signed link can accept. Takes effect at once; not a version."},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete terms that nobody has accepted (owner and admins)","description":"Answers 409 once anyone has accepted them: records are kept for as long as the account exists. Close them instead.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwraps/{id}/publish":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Publish the draft as the next version (owner and admins)","description":"Any change to the terms, their name, the words of the box or the button, or the scrolling rule is a new version; nothing changed answers 409. From version 2 a \"note\" of what changed is needed: people asked to accept again are shown it. \"ask_again\" (default true) makes everyone who accepted an earlier version accept again; false keeps earlier acceptances counting, for a correction that changes no meaning. Answers how many people are asked again, in \"asked_again\" and in words in \"again\". 422 when the terms read like a fake payment notice, carry a well-known brand's name, or are a PDF of pictures, for an account that has not earned trust. 403 while the account is paused.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"note":{"type":"string","maxLength":500},"ask_again":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"integer"},"sha256":{"type":"string"},"asked_again":{"type":"integer"},"again":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwraps/{id}/secret":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Make a new key for the links the website signs (owner and admins)","description":"Links signed with the old key stop working at once.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"secret":{"type":"string"},"note":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwraps/{id}/acceptances":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Record an acceptance your website collected itself (any key)","description":"For terms the website showed on its own pages. The record says everywhere that the website recorded it through the API and that Sign&Grow did not see a click, with who made the call. \"version\", when given, must be the version that is live (409 otherwise). The same person (by id, or by email when there is no id) on the same version is one record: the answer is the first one with \"already\": true. 409 with \"code\": \"closed\" when the terms are not taking acceptances, with the reason. 429 with \"code\": \"monthly_limit\" when the account has recorded 1000 acceptances this calendar month (UTC); the admins are emailed at 80 percent and when it is reached.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["person"],"properties":{"person":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}},"description":"id (your own) or email is needed."},"version":{"type":"integer"},"page_url":{"type":"string"},"ip":{"type":"string","description":"The visitor's address, as you saw it."},"user_agent":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"acceptance":{"type":"object","description":"One acceptance, as it was recorded. It is never changed afterwards.","properties":{"id":{"type":"string"},"agreement_id":{"type":"string"},"agreement":{"type":"string"},"version":{"type":"integer"},"terms_sha256":{"type":"string","description":"SHA-256 of the exact terms shown: of the text as written, or of the PDF file."},"accepted_at":{"type":"string","format":"date-time"},"identity":{"type":"string","enum":["website","typed","api"],"description":"\"website\": the details came in a link the website signed with the key of the agreement. \"typed\": the visitor typed them and nobody checked them. \"api\": the website sent them through POST /clickwraps/{id}/acceptances."},"person":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"via":{"type":"string","enum":["hosted","embed","api"]},"page_url":{"type":"string","nullable":true,"description":"The page it came from, as the browser reported it (or as the website said, for \"api\")."},"ip":{"type":"string"},"user_agent":{"type":"string"},"given_ip":{"type":"string","nullable":true,"description":"\"api\" only: the visitor's address as the website gave it."},"given_user_agent":{"type":"string","nullable":true},"seconds_open":{"type":"number","nullable":true,"description":"How long the terms were open before the press, measured by this server."},"scrolled":{"type":"boolean","nullable":true},"button_uncovered":{"type":"boolean","nullable":true,"description":"Whether the browser said nothing covered the button (Chrome and Edge can tell); null where it could not tell."},"recorded_by":{"type":"string","nullable":true},"intact":{"type":"boolean","description":"false when the stored record no longer fits the seal it was written with."}}},"already":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwraps/{id}/status":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Has this person accepted the version that counts? (any key)","description":"By person_id (your own id: only acceptances from your signed links or the API carry one) or by email. \"accepted\" is true when their newest acceptance is of \"counts_from_version\" or later. \"latest.identity\" says how that acceptance came about: a visitor can type anybody's email address, so decide which kinds you trust.","parameters":[{"name":"person_id","in":"query","schema":{"type":"string"}},{"name":"email","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"agreement_id":{"type":"string"},"current_version":{"type":"integer","nullable":true},"counts_from_version":{"type":"integer","nullable":true},"accepted":{"type":"boolean"},"latest":{"type":"object","description":"One acceptance, as it was recorded. It is never changed afterwards.","properties":{"id":{"type":"string"},"agreement_id":{"type":"string"},"agreement":{"type":"string"},"version":{"type":"integer"},"terms_sha256":{"type":"string","description":"SHA-256 of the exact terms shown: of the text as written, or of the PDF file."},"accepted_at":{"type":"string","format":"date-time"},"identity":{"type":"string","enum":["website","typed","api"],"description":"\"website\": the details came in a link the website signed with the key of the agreement. \"typed\": the visitor typed them and nobody checked them. \"api\": the website sent them through POST /clickwraps/{id}/acceptances."},"person":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"via":{"type":"string","enum":["hosted","embed","api"]},"page_url":{"type":"string","nullable":true,"description":"The page it came from, as the browser reported it (or as the website said, for \"api\")."},"ip":{"type":"string"},"user_agent":{"type":"string"},"given_ip":{"type":"string","nullable":true,"description":"\"api\" only: the visitor's address as the website gave it."},"given_user_agent":{"type":"string","nullable":true},"seconds_open":{"type":"number","nullable":true,"description":"How long the terms were open before the press, measured by this server."},"scrolled":{"type":"boolean","nullable":true},"button_uncovered":{"type":"boolean","nullable":true,"description":"Whether the browser said nothing covered the button (Chrome and Edge can tell); null where it could not tell."},"recorded_by":{"type":"string","nullable":true},"intact":{"type":"boolean","description":"false when the stored record no longer fits the seal it was written with."}},"nullable":true},"versions_accepted":{"type":"array","items":{"type":"integer"}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwrap-acceptances":{"get":{"summary":"Look acceptances up (owner and admins)","description":"Newest first, 50 at a time (up to 200 with \"limit\"); \"next_before\" goes further back. \"total\" counts every match.","parameters":[{"name":"agreement","in":"query","schema":{"type":"string"},"description":"An agreement id."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Part of a name, an email address or the website's id for the person, or a whole acceptance id."},{"name":"version","in":"query","schema":{"type":"integer"}},{"name":"via","in":"query","schema":{"type":"string","enum":["hosted","embed","api"]}},{"name":"identity","in":"query","schema":{"type":"string","enum":["website","typed","api"]}},{"name":"from","in":"query","schema":{"type":"string"},"description":"A day, YYYY-MM-DD, in UTC."},{"name":"to","in":"query","schema":{"type":"string"},"description":"A day, YYYY-MM-DD, in UTC, counted in."},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"before","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"total":{"type":"integer"},"acceptances":{"type":"array","items":{"type":"object","description":"One acceptance, as it was recorded. It is never changed afterwards.","properties":{"id":{"type":"string"},"agreement_id":{"type":"string"},"agreement":{"type":"string"},"version":{"type":"integer"},"terms_sha256":{"type":"string","description":"SHA-256 of the exact terms shown: of the text as written, or of the PDF file."},"accepted_at":{"type":"string","format":"date-time"},"identity":{"type":"string","enum":["website","typed","api"],"description":"\"website\": the details came in a link the website signed with the key of the agreement. \"typed\": the visitor typed them and nobody checked them. \"api\": the website sent them through POST /clickwraps/{id}/acceptances."},"person":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"via":{"type":"string","enum":["hosted","embed","api"]},"page_url":{"type":"string","nullable":true,"description":"The page it came from, as the browser reported it (or as the website said, for \"api\")."},"ip":{"type":"string"},"user_agent":{"type":"string"},"given_ip":{"type":"string","nullable":true,"description":"\"api\" only: the visitor's address as the website gave it."},"given_user_agent":{"type":"string","nullable":true},"seconds_open":{"type":"number","nullable":true,"description":"How long the terms were open before the press, measured by this server."},"scrolled":{"type":"boolean","nullable":true},"button_uncovered":{"type":"boolean","nullable":true,"description":"Whether the browser said nothing covered the button (Chrome and Edge can tell); null where it could not tell."},"recorded_by":{"type":"string","nullable":true},"intact":{"type":"boolean","description":"false when the stored record no longer fits the seal it was written with."}}}},"next_before":{"type":"integer","nullable":true}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwrap-acceptances/export":{"get":{"summary":"The same as CSV (owner and admins)","description":"UTF-8 with a byte order mark. A cell that starts with =, +, - or @ gets a ' in front, so a typed name cannot run as a formula in a spreadsheet.","parameters":[{"name":"agreement","in":"query","schema":{"type":"string"},"description":"An agreement id."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Part of a name, an email address or the website's id for the person, or a whole acceptance id."},{"name":"version","in":"query","schema":{"type":"integer"}},{"name":"via","in":"query","schema":{"type":"string","enum":["hosted","embed","api"]}},{"name":"identity","in":"query","schema":{"type":"string","enum":["website","typed","api"]}},{"name":"from","in":"query","schema":{"type":"string"},"description":"A day, YYYY-MM-DD, in UTC."},{"name":"to","in":"query","schema":{"type":"string"},"description":"A day, YYYY-MM-DD, in UTC, counted in."}],"responses":{"200":{"description":"CSV","content":{"text/csv":{"schema":{"type":"string"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwrap-acceptances/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"One acceptance, with what its record shows and does not (owner and admins)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"acceptance":{"type":"object","description":"One acceptance, as it was recorded. It is never changed afterwards.","properties":{"id":{"type":"string"},"agreement_id":{"type":"string"},"agreement":{"type":"string"},"version":{"type":"integer"},"terms_sha256":{"type":"string","description":"SHA-256 of the exact terms shown: of the text as written, or of the PDF file."},"accepted_at":{"type":"string","format":"date-time"},"identity":{"type":"string","enum":["website","typed","api"],"description":"\"website\": the details came in a link the website signed with the key of the agreement. \"typed\": the visitor typed them and nobody checked them. \"api\": the website sent them through POST /clickwraps/{id}/acceptances."},"person":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}}},"via":{"type":"string","enum":["hosted","embed","api"]},"page_url":{"type":"string","nullable":true,"description":"The page it came from, as the browser reported it (or as the website said, for \"api\")."},"ip":{"type":"string"},"user_agent":{"type":"string"},"given_ip":{"type":"string","nullable":true,"description":"\"api\" only: the visitor's address as the website gave it."},"given_user_agent":{"type":"string","nullable":true},"seconds_open":{"type":"number","nullable":true,"description":"How long the terms were open before the press, measured by this server."},"scrolled":{"type":"boolean","nullable":true},"button_uncovered":{"type":"boolean","nullable":true,"description":"Whether the browser said nothing covered the button (Chrome and Edge can tell); null where it could not tell."},"recorded_by":{"type":"string","nullable":true},"intact":{"type":"boolean","description":"false when the stored record no longer fits the seal it was written with."}}},"shows":{"type":"object","properties":{"shows":{"type":"string"},"not":{"type":"string"}}},"law":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/clickwrap-acceptances/{id}/certificate":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The certificate of one acceptance, as PDF (owner and admins)","description":"The record, what it shows and what it does not, whether it still fits its seal, and the terms as shown (a PDF's pages follow). Whether accepting terms with a click binds someone depends on the country, on the kind of agreement and on how the terms were shown. Rules differ, and some agreements need a signature or a particular form. Check what applies to yours.","responses":{"200":{"description":"A PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/agree/{slug}":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"What the page /agree/{slug} shows","security":[],"description":"The live version, what is recorded and what a record shows, and a \"view\" to accept with. \"who\" and \"sig\" in the query name the visitor: \"who\" is base64url of JSON {id, name, email, exp}, \"sig\" the HMAC-SHA256 of that exact text with the key of the agreement, in base64url or hex. \"exp\" (seconds since 1970) is required and at most 30 days ahead. A link that does not check out is refused in words with a \"code\" (who_not_signed, who_expired, who_exp_ms, who_no_exp, who_exp_far, who_nobody, who_bad_email, who_incomplete, who_unreadable) and never falls back to typed details. Terms that cannot be accepted answer \"closed\": true with a sentence and nothing else.","parameters":[{"name":"who","in":"query","schema":{"type":"string"}},{"name":"sig","in":"query","schema":{"type":"string"}},{"name":"embed","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/agree/{slug}/terms":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The PDF of the live terms, when they are a PDF","security":[],"responses":{"200":{"description":"A PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/agree/{slug}/accept":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Accept, from the page or the frame","security":[],"description":"Needs the \"view\" of the page: a press always belongs to the version that was on the screen (409 \"terms_changed\" when a new version came in between, \"view_old\" after 24 hours). \"agree\" must be true. With \"scrolled\" true when the terms ask for it. Without \"who\" and \"sig\", \"name\" and \"email\" are needed, unless the agreement takes only people the website names (403 \"signed_only\"). Answers the acceptance and a \"receipt\", the visitor's own secret for the copy by email and the certificate; it is kept nowhere but in that answer. 30 acceptances an hour from one address, 10 on one agreement. 429 \"monthly_limit\" says only that the terms cannot be accepted right now.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["view","agree"],"properties":{"view":{"type":"string"},"agree":{"type":"boolean"},"scrolled":{"type":"boolean"},"who":{"type":"string"},"sig":{"type":"string"},"name":{"type":"string"},"email":{"type":"string"},"embed":{"type":"boolean"},"page_url":{"type":"string"},"unobscured":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"acceptance":{"type":"object"},"receipt":{"type":"string"},"already":{"type":"boolean"},"email":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/agree/receipt/email":{"post":{"summary":"Email the visitor a copy of what they accepted","security":[],"description":"To the address recorded with the acceptance, with the certificate attached. Once an hour for each acceptance; 409 when no address was given.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["receipt"],"properties":{"receipt":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"sent":{"type":"boolean"},"status":{"type":"string"},"to":{"type":"string"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/agree/receipt/{receipt}/certificate":{"parameters":[{"name":"receipt","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"The visitor's certificate, by their receipt","security":[],"responses":{"200":{"description":"A PDF file","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/agree/{slug}/report":{"parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"post":{"summary":"Report the page as suspicious","security":[],"description":"Goes to the people who review reports. Anyone can open such a page, so a report never counts towards pausing the account by itself.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"},"detail":{"type":"string"},"email":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"already":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/public/check/report":{"post":{"summary":"Report the email a security code came from, without opening its signing link","description":"Counts exactly like a report made on the signing page: enough different recipients reporting one account pause its sending until a person has looked. The code of an email whose document the sender has deleted since still works: the report is filed against the account that sent it, and the answer has \"deleted\": true. A report from the visitor of a public form is kept for a person to look at and does not count towards the pause. Answers 404 for a code we do not recognise, and for a code whose document and account are both gone.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["code"],"properties":{"code":{"type":"string"},"reason":{"type":"string","enum":["phishing","spam","not-for-me","other"]},"detail":{"type":"string"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}