{"openapi":"3.1.0","info":{"title":"readyink.ai API","version":"1.0.0","description":"Send PDFs for signature from your own software and fetch the signed copy when everyone has signed. Create keys under Settings › Developers in the readyink.ai app. `ri_test_…` keys use the sandbox: free sends, emails and texts go to your test inbox, and the text code is always 000000.\n\nSee the full guide (quickstart, conventions, errors, reference tables) in the readyink.ai API reference.","contact":{"name":"readyink.ai support","url":"https://readyink.ai"}},"servers":[{"url":"https://api.readyink.ai/v1"}],"security":[{"bearer":[]}],"tags":[{"name":"Account"},{"name":"Documents"},{"name":"Recipients"},{"name":"Fields"},{"name":"Sending","description":"Quote, send and cancel"},{"name":"Results","description":"Signed PDF, certificate and activity"}],"paths":{"/account":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"Get the account and token balance","responses":{"200":{"description":"The account the key belongs to","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents":{"get":{"tags":["Documents"],"operationId":"listDocuments","summary":"List documents (newest first)","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"starting_after","in":"query","description":"The `next_cursor` from the previous page","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/DocumentStatus"}},{"name":"created_after","in":"query","description":"Only documents created after this time","schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"A page of documents","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentList"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`invalid_limit`, `invalid_date`, `invalid`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}},"post":{"tags":["Documents"],"operationId":"createDocument","summary":"Create a draft","description":"Create a draft, optionally with the PDF (multipart `file`) and recipients. All or nothing: if any part fails, nothing is created. With a PDF, `file_status` starts as `processing` and becomes `ready` within seconds; add fields once it's ready.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentCreate"},"example":{"title":"NDA","recipients":[{"name":"Ana Diaz","email":"ana@example.com"}]}},"multipart/form-data":{"schema":{"type":"object","required":["data"],"properties":{"file":{"type":"string","format":"binary","description":"The PDF (up to 25 MB)"},"data":{"type":"string","description":"The JSON body (DocumentCreate) as a string"}}}}}},"responses":{"201":{"description":"The new draft","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"Unreadable body (`invalid_json`, `invalid_multipart`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`duplicate_email`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The PDF is too big (`file_too_large`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`validation_failed`, `invalid_recipient`, `empty_file`, `not_a_pdf`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"get":{"tags":["Documents"],"operationId":"getDocument","summary":"Get a document","responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}},"patch":{"tags":["Documents"],"operationId":"updateDocument","summary":"Change title, signing mode or reminders","description":"`title` and `signing_mode` change on drafts; `reminder_days` also while the document is out.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DocumentSettings"}}}},"responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_editable`, `bad_state`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`validation_failed`, `invalid`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}},"delete":{"tags":["Documents"],"operationId":"deleteDocument","summary":"Delete a draft","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Deleted"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_editable`: sent documents can be cancelled instead)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/file":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"post":{"tags":["Documents"],"operationId":"uploadFile","summary":"Upload the PDF","description":"For a draft created without a PDF. Multipart `file`, or the raw bytes with `Content-Type: application/pdf`. Once per document.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary","description":"The PDF (up to 25 MB)"}}}},"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"The document, with `file_status: processing`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`bad_state`: the PDF was already uploaded; `not_editable`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"The PDF is too big (`file_too_large`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Use multipart/form-data or application/pdf","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`empty_file`, `not_a_pdf`, `missing_file`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/recipients":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"post":{"tags":["Recipients"],"operationId":"addRecipient","summary":"Add a recipient (drafts)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecipientInput"},"example":{"name":"Ana Diaz","email":"ana@example.com"}}}},"responses":{"201":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_editable`, `duplicate_email`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`validation_failed`, `invalid`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/recipients/{rid}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}},{"name":"rid","in":"path","required":true,"description":"The recipient's ID (`rcp_…`)","schema":{"type":"string","pattern":"^rcp_"}}],"patch":{"tags":["Recipients"],"operationId":"updateRecipient","summary":"Change a recipient","description":"On a draft, send the full recipient. On a document that's out, send exactly `{\"email\": \"…\"}`: the old link stops working and a new request goes to the new address.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RecipientInput"},{"$ref":"#/components/schemas/RecipientEmailChange"}]}}}},"responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_editable`, `duplicate_email`, `bad_state`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`validation_failed`, `invalid`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}},"delete":{"tags":["Recipients"],"operationId":"removeRecipient","summary":"Remove a recipient (drafts; their fields go too)","responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_editable`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/fields":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"post":{"tags":["Fields"],"operationId":"addFields","summary":"Add one field or many","description":"Send one field, or up to 200 as `{\"fields\": [...]}`. All or nothing. The pages must be ready (`file_status: ready`). Positions are 0–1 fractions of the page from the top-left corner.","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/FieldInput"},{"type":"object","required":["fields"],"properties":{"fields":{"type":"array","minItems":1,"maxItems":200,"items":{"$ref":"#/components/schemas/FieldInput"}}}}]},"example":{"fields":[{"type":"signature","recipient_id":"rcp_def456","page":1,"x":0.1,"y":0.8,"w":0.28,"h":0.035}]}}}},"responses":{"201":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`file_not_ready`, `not_editable`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`invalid_field`, `invalid_fields`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/fields/{fid}":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}},{"name":"fid","in":"path","required":true,"description":"The field's ID (`fld_…`)","schema":{"type":"string","pattern":"^fld_"}}],"patch":{"tags":["Fields"],"operationId":"updateField","summary":"Move, resize or change a field (drafts)","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FieldPatch"}}}},"responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_editable`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Invalid input (`validation_failed`, `invalid`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}},"delete":{"tags":["Fields"],"operationId":"deleteField","summary":"Remove a field (drafts)","responses":{"200":{"description":"The document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_editable`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/quote":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"get":{"tags":["Sending"],"operationId":"getQuote","summary":"Cost to send now, and anything to fix first","responses":{"200":{"description":"The quote","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/send":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"post":{"tags":["Sending"],"operationId":"sendDocument","summary":"Send for signature","description":"Requires `Idempotency-Key`, so a retry never sends or charges twice. Rate limited to 10 a minute per key. Test keys send for 0 tokens.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique string (up to 200 characters). A retry with the same key and request returns the first response with `Idempotent-Replayed: true`; the same key with a different request is a 409. Remembered per API key for 24 hours.","schema":{"type":"string","maxLength":200}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_tokens":{"type":"integer","minimum":0,"description":"The `tokens` from your quote; refused with 409 `quote_changed` if the cost changed"}}}}}},"responses":{"200":{"description":"The document, with `status: out`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Document"}}}},"400":{"description":"`idempotency_key_required`, `idempotency_key_too_long`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough tokens (`insufficient_tokens`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientTokensError"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`quote_changed` (with `tokens`), `bad_state`, `idempotency_conflict`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Something must be fixed first (`not_ready_to_send`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NotReadyError"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"post":{"tags":["Sending"],"operationId":"cancelDocument","summary":"Cancel a document that's out","description":"Links stop working and pending signers are emailed. Tokens come back only if no one had opened it (`tokens_returned`). Requires `Idempotency-Key`.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"A unique string (up to 200 characters). A retry with the same key and request returns the first response with `Idempotent-Replayed: true`; the same key with a different request is a 409. Remembered per API key for 24 hours.","schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"The document, with `status: cancelled`","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Document"},{"type":"object","properties":{"tokens_returned":{"type":"integer"}}}]}}}},"400":{"description":"`idempotency_key_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`bad_state`, `idempotency_conflict`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/signed-pdf":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"get":{"tags":["Results"],"operationId":"getSignedPdf","summary":"Download the signed PDF","description":"Redirects to a download link valid for 10 minutes. Completed documents only.","responses":{"302":{"description":"Redirect to the sealed PDF","headers":{"Location":{"schema":{"type":"string"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_completed`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/certificate":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"get":{"tags":["Results"],"operationId":"getCertificate","summary":"Download the certificate of completion","description":"Redirects to a download link valid for 10 minutes. Completed documents only.","responses":{"302":{"description":"Redirect to the certificate","headers":{"Location":{"schema":{"type":"string"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (`not_completed`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}},"/documents/{id}/events":{"parameters":[{"name":"id","in":"path","required":true,"description":"The document's ID (`doc_…`)","schema":{"type":"string","pattern":"^doc_"}}],"get":{"tags":["Results"],"operationId":"listEvents","summary":"The document's activity (oldest first)","responses":{"200":{"description":"Events","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EventList"}}}},"401":{"description":"Missing, wrong or revoked API key (`missing_key`, `invalid_key`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"No such document, recipient or field in this mode","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited (`rate_limited`). Wait `Retry-After` seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait"}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"`Authorization: Bearer ri_live_…` or `ri_test_…` (sandbox)"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["type","code","message","doc_url"],"properties":{"type":{"type":"string","enum":["invalid_request","authentication_error","payment_required","forbidden","not_found","conflict","rate_limit_error","api_error"]},"code":{"type":"string","description":"The specific reason; branch on this"},"message":{"type":"string","description":"A sentence you can show a person"},"param":{"type":"string","description":"The input it's about (dot path)"},"doc_url":{"type":"string"}},"additionalProperties":true}}},"InsufficientTokensError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"needed":{"type":"integer"},"available":{"type":"integer"},"checkout_url":{"type":"string","description":"For a person to buy tokens"}}}}}]},"NotReadyError":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"error":{"type":"object","properties":{"problems":{"type":"array","items":{"type":"string"}}}}}}]},"Account":{"type":"object","properties":{"object":{"const":"account"},"name":{"type":"string"},"plan":{"type":"string","enum":["pay_as_you_go","team"]},"mode":{"type":"string","enum":["live","test"],"description":"The mode of the key used"},"key_name":{"type":"string"},"balance":{"type":"object","properties":{"available":{"type":"integer"},"reserved":{"type":"integer","description":"Held for sends in progress"},"monthly":{"type":"integer","description":"Team plan's monthly tokens left"}}},"tokens_per_recipient":{"type":"integer"}}},"DocumentStatus":{"type":"string","enum":["draft","sending","out","completed","declined","cancelled","send_failed"]},"Document":{"type":"object","properties":{"id":{"type":"string","examples":["doc_c9x1q8"]},"object":{"const":"document"},"title":{"type":"string"},"status":{"$ref":"#/components/schemas/DocumentStatus"},"test_mode":{"type":"boolean"},"signing_mode":{"type":"string","enum":["parallel","sequential"]},"reminder_days":{"type":["integer","null"],"enum":[1,3,7,null]},"file_status":{"type":"string","enum":["awaiting_upload","processing","ready","failed"]},"file_error":{"type":["string","null"]},"page_count":{"type":["integer","null"]},"readyink_id":{"type":["string","null"],"description":"Stamped on the signed copy; set when sealed"},"send_error":{"type":["string","null"]},"cost":{"type":"object","properties":{"signers":{"type":"integer"},"tokens":{"type":"integer"}}},"version_hash":{"type":["string","null"],"description":"SHA-256 of what was sent"},"final_hash":{"type":["string","null"],"description":"SHA-256 of the sealed PDF"},"created_at":{"type":"string","format":"date-time"},"sent_at":{"type":["string","null"],"format":"date-time"},"completed_at":{"type":["string","null"],"format":"date-time"},"delete_after":{"type":["string","null"],"format":"date-time"},"recipients":{"type":"array","items":{"$ref":"#/components/schemas/Recipient"}},"fields":{"type":"array","items":{"$ref":"#/components/schemas/Field"}}}},"DocumentList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Document"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}}},"DocumentSettings":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"signing_mode":{"type":"string","enum":["parallel","sequential"],"default":"parallel"},"reminder_days":{"type":["integer","null"],"enum":[1,3,7,null],"default":7}}},"DocumentCreate":{"allOf":[{"$ref":"#/components/schemas/DocumentSettings"},{"type":"object","required":["title"],"properties":{"recipients":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/RecipientInput"}}}}]},"Deleted":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"document"},"deleted":{"const":true}}},"RecipientInput":{"type":"object","required":["name","email"],"properties":{"name":{"type":"string"},"email":{"type":"string","format":"email"},"mobile":{"type":"string","description":"US mobile number; needed for sms or both"},"notify_via":{"type":"string","enum":["email","sms","both"],"default":"email"},"role":{"type":"string","enum":["signer","copy"],"default":"signer","description":"`copy` recipients get the signed copy, sign nothing and cost nothing"}}},"RecipientEmailChange":{"type":"object","required":["email"],"additionalProperties":false,"properties":{"email":{"type":"string","format":"email"}}},"Recipient":{"type":"object","properties":{"id":{"type":"string","examples":["rcp_def456"]},"object":{"const":"recipient"},"name":{"type":"string"},"email":{"type":"string"},"mobile_last4":{"type":["string","null"]},"notify_via":{"type":"string","enum":["email","sms","both"]},"role":{"type":"string","enum":["signer","copy"]},"order":{"type":"integer","minimum":1},"status":{"type":"string","enum":["pending","notified","viewed","signed","declined"]},"signed_at":{"type":["string","null"],"format":"date-time"},"declined_at":{"type":["string","null"],"format":"date-time"}}},"FieldType":{"type":"string","enum":["signature","initials","date","name","email","phone","company","job_title","address","website","short_text","long_text","number","dropdown","single_choice","multiple_choice"]},"FieldInput":{"type":"object","required":["type","recipient_id","page","x","y","w","h"],"properties":{"type":{"$ref":"#/components/schemas/FieldType"},"recipient_id":{"type":"string"},"page":{"type":"integer","minimum":1},"x":{"type":"number","minimum":0,"maximum":1,"description":"Left edge, fraction of page width"},"y":{"type":"number","minimum":0,"maximum":1,"description":"Top edge, fraction of page height"},"w":{"type":"number","minimum":0,"maximum":1},"h":{"type":"number","minimum":0,"maximum":1},"required":{"type":"boolean","default":true},"options":{"type":"object","description":"Text types: placeholder, maxLength, prefill. number: min, max, decimals. dropdown, single_choice, multiple_choice: choices (required). Others: {}."}}},"FieldPatch":{"type":"object","properties":{"recipient_id":{"type":"string"},"page":{"type":"integer","minimum":1},"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"},"options":{"type":"object"}}},"Field":{"type":"object","properties":{"id":{"type":"string","examples":["fld_9q2k"]},"object":{"const":"field"},"type":{"$ref":"#/components/schemas/FieldType"},"recipient_id":{"type":"string"},"page":{"type":"integer"},"x":{"type":"number"},"y":{"type":"number"},"w":{"type":"number"},"h":{"type":"number"},"required":{"type":"boolean"},"options":{"type":"object"}}},"Quote":{"type":"object","properties":{"object":{"const":"quote"},"document_id":{"type":"string"},"signers":{"type":"integer"},"copies":{"type":"integer"},"tokens":{"type":"integer"},"balance_available":{"type":"integer"},"balance_after":{"type":"integer"},"enough_tokens":{"type":"boolean"},"problems":{"type":"array","items":{"type":"string"},"description":"Empty when it can be sent"},"can_send":{"type":"boolean"}}},"Event":{"type":"object","properties":{"id":{"type":"string"},"object":{"const":"event"},"type":{"type":"string","description":"What happened. Current types: `sent`, `sender_not_signing`, `self_sign`, `send_failed`, `notified`, `cancelled`, `recipient_email_changed`, `texted`, `text_reminded`, `text_delivered`, `text_failed`, `text_not_sent`, `reminded`, `opened`, `code_sent`, `verified`, `verify_failed`, `verify_locked`, `sample_opened`, `consented`, `link_reissued`, `signed`, `declined`, `completed`, `sealed`, `delivered`, `downloaded`, `ai_created`, `ai_suggested`, `ai_accepted`. New types may be added; show `description` for any you don't recognize.","examples":["sent","signed","completed"]},"description":{"type":"string"},"actor":{"type":"string","enum":["owner","api","recipient","system","admin","ai_claude","ai_chatgpt"]},"recipient_id":{"type":["string","null"]},"created_at":{"type":"string","format":"date-time"}}},"EventList":{"type":"object","properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}},"has_more":{"type":"boolean"}}}}}}