{"openapi":"3.1.0","info":{"title":"OkoSign API","version":"1","description":"Prepare documents, send them for qualified electronic signatures with Smart-ID, follow their progress and fetch the signed files. Only the person signs, with PIN2 on their own phone. Every error is `{ code, message }`."},"servers":[{"url":"https://app.okosign.com/v1"}],"externalDocs":{"description":"Quickstart","url":"https://app.okosign.com/docs/quickstart.md"},"security":[{"apiKey":[]},{"oauth2":["okosign"]}],"paths":{"/account":{"get":{"operationId":"get_account","summary":"Your OkoSign account","description":"Who is signed in to OkoSign through this connection, whether their identity is confirmed, and how many signatures are left in this period.","responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":["string","null"]},"email":{"type":"string"},"language":{"type":"string","enum":["lv","et","lt","en","ru"]}},"required":["id","name","email","language"],"additionalProperties":false},"workspace":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"country":{"type":"string","enum":["LV","EE","LT"]},"textInvites":{"type":"boolean"},"demo":{"type":"boolean"}},"required":["id","name","country","textInvites","demo"],"additionalProperties":false},"identityConfirmed":{"type":"boolean"},"allowance":{"type":"object","properties":{"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"included":{"type":"integer"},"used":{"type":"integer"},"reserved":{"type":"integer"},"bonusLeft":{"type":"integer"},"extrasThisPeriod":{"type":"integer"},"freeLeft":{"type":"integer"}},"required":["periodStart","periodEnd","included","used","reserved","bonusLeft","extrasThisPeriod","freeLeft"],"additionalProperties":false},"referralUrl":{"type":["string","null"]}},"required":["user","workspace","identityConfirmed","allowance","referralUrl"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/people":{"get":{"operationId":"find_person","summary":"Find a person","description":"Find people this OkoSign account has sent documents to before, and teammates, by the first letters of a name or an email address. At most 10.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"people":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string","enum":["contact","user"]},"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"source":{"type":"string","enum":["history","google","microsoft","team"]},"lastSentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"timesSent":{"type":"integer"}},"required":["kind","id","name","email","phone","language","source","lastSentAt","timesSent"],"additionalProperties":false}}},"required":["people"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/documents/from-markdown":{"post":{"operationId":"make_pdf","summary":"Make a PDF from text","description":"Turn Markdown into a typeset A4 PDF (headings, lists, tables, page numbers; Latvian, Lithuanian, Estonian and Russian letters). Images and raw HTML are left out and listed in `dropped`. The PDF is stored as is and is never changed afterwards.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"markdown":{"type":"string","minLength":1,"maxLength":200000},"language":{"type":"string","enum":["lv","et","lt","en","ru"]}},"required":["title","markdown"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created. The answer describes what was made.","content":{"application/json":{"schema":{"type":"object","properties":{"documentId":{"type":"string","pattern":"^upl_[A-Za-z0-9]{16}$"},"name":{"type":"string"},"pages":{"type":"integer"},"dropped":{"type":"array","items":{"type":"string","enum":["image","html","footnote","nested_table"]}}},"required":["documentId","name","pages","dropped"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/uploads":{"post":{"operationId":"upload_document","summary":"Upload a document","description":"Store one file to sign: a PDF or any document type OkoSign accepts. Over MCP the file is base64 in `contentBase64` (at most about 700 KB); larger files go through POST /v1/uploads as raw bytes.","parameters":[{"name":"X-File-Name","in":"header","required":false,"schema":{"type":"string","maxLength":300},"description":"The file's name, percent-encoded UTF-8."}],"requestBody":{"required":true,"description":"The file's bytes, at most 26214400 bytes.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}},"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"201":{"description":"Created. The answer describes what was made.","content":{"application/json":{"schema":{"type":"object","properties":{"uploadId":{"type":"string","pattern":"^upl_[A-Za-z0-9]{16}$"},"name":{"type":"string"},"bytes":{"type":"integer"},"pages":{"type":["integer","null"]}},"required":["uploadId","name","bytes","pages"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"413":{"description":"The file is larger than OkoSign accepts (`too_large`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"415":{"description":"The body is not a file of a type this operation takes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests":{"post":{"operationId":"create_request","summary":"Prepare a signing request","description":"Create a signing request as a draft: the documents (uploadId or documentId), the people who sign or receive a copy, and optionally the invite's wording, the sender name, and a deadline. With iSign the person signs first, before anyone else gets it. Nothing is sent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"documents":{"minItems":1,"maxItems":10,"type":"array","items":{"anyOf":[{"type":"object","properties":{"uploadId":{"type":"string","pattern":"^upl_[A-Za-z0-9]{16}$"}},"required":["uploadId"],"additionalProperties":false},{"type":"object","properties":{"documentId":{"type":"string","pattern":"^upl_[A-Za-z0-9]{16}$"}},"required":["documentId"],"additionalProperties":false}]}},"iSign":{"default":false,"type":"boolean"},"signingOrder":{"default":true,"type":"boolean"},"recipients":{"minItems":0,"maxItems":20,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":32},"role":{"default":"signer","type":"string","enum":["signer","viewer"]},"step":{"type":"integer","minimum":1},"channel":{"default":"email","type":"string","enum":["email","sms","both"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"message":{"type":"string","maxLength":1000}},"required":["name"],"additionalProperties":false}},"invite":{"type":"object","properties":{"subject":{"type":"string","maxLength":120},"message":{"type":"string","maxLength":1000},"smsText":{"type":"string","maxLength":120},"fromName":{"type":"string","maxLength":60},"replyTo":{"type":"string","format":"email"}},"additionalProperties":false},"dueAt":{"type":"string","format":"date-time"}},"required":["title","documents","recipients"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created. The answer describes what was made.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["pdf","asice"]},{"type":"null"}]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"pages":{"type":["integer","null"]}},"required":["id","name","pages"],"additionalProperties":false}},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"type":"string","enum":["signer","viewer"]},"step":{"type":["integer","null"]},"channel":{"type":"string","enum":["email","sms","both"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"status":{"type":"string","enum":["waiting","sent","opened","signed","declined","bounced"]},"isYou":{"type":"boolean"},"openedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","email","phone","role","step","channel","language","status","isYou","openedAt","signedAt","declinedAt"],"additionalProperties":false}},"files":{"type":"object","properties":{"signed":{"type":"boolean"},"certificate":{"type":"boolean"},"copies":{"type":"integer"}},"required":["signed","certificate","copies"],"additionalProperties":false},"preparedBy":{"type":["string","null"]},"sentBy":{"type":["string","null"]},"confirmation":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","declined","expired"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["status","expiresAt"],"additionalProperties":false},{"type":"null"}]},"mySession":{"anyOf":[{"type":"object","properties":{"sessionId":{"type":"string"},"phase":{"type":"string"},"code":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time"}},"required":["sessionId","phase","code","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["ref","title","status","createdAt","sentAt","completedAt","dueAt","format","documents","recipients","files","preparedBy","sentBy","confirmation","mySession"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]},"get":{"operationId":"list_requests","summary":"Your signing requests","description":"The account's signing requests, newest first.","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":50}},{"name":"offset","in":"query","required":false,"schema":{"default":0,"type":"integer","minimum":0}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"ref":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedCount":{"type":"integer"},"signerCount":{"type":"integer"}},"required":["ref","title","status","sentAt","dueAt","signedCount","signerCount"],"additionalProperties":false}},"total":{"type":"integer"}},"required":["items","total"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests/{ref}/preview":{"post":{"operationId":"preview_invite","summary":"Preview the invite","description":"Exactly what each person will receive when the draft is sent: the sender, the subject, the message, and the text message.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"senderLine":{"type":"string"},"people":{"type":"array","items":{"type":"object","properties":{"recipientId":{"type":"integer"},"name":{"type":"string"},"channel":{"type":"string","enum":["email","sms","both"]},"email":{"anyOf":[{"type":"object","properties":{"from":{"type":"string"},"subject":{"type":"string"},"text":{"type":"string"}},"required":["from","subject","text"],"additionalProperties":false},{"type":"null"}]},"sms":{"anyOf":[{"type":"object","properties":{"body":{"type":"string"}},"required":["body"],"additionalProperties":false},{"type":"null"}]}},"required":["recipientId","name","channel","email","sms"],"additionalProperties":false}}},"required":["senderLine","people"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests/{ref}/send":{"post":{"operationId":"send_request","summary":"Send for signing","description":"Send a draft to its people. If the person has to agree first, the answer is confirmation_required with a link for them; nothing is sent until they say yes there, or until they sign the document themselves first (signToConfirm).","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"sent"},"request":{"type":"object","properties":{"ref":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["pdf","asice"]},{"type":"null"}]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"pages":{"type":["integer","null"]}},"required":["id","name","pages"],"additionalProperties":false}},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"type":"string","enum":["signer","viewer"]},"step":{"type":["integer","null"]},"channel":{"type":"string","enum":["email","sms","both"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"status":{"type":"string","enum":["waiting","sent","opened","signed","declined","bounced"]},"isYou":{"type":"boolean"},"openedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","email","phone","role","step","channel","language","status","isYou","openedAt","signedAt","declinedAt"],"additionalProperties":false}},"files":{"type":"object","properties":{"signed":{"type":"boolean"},"certificate":{"type":"boolean"},"copies":{"type":"integer"}},"required":["signed","certificate","copies"],"additionalProperties":false},"preparedBy":{"type":["string","null"]},"sentBy":{"type":["string","null"]},"confirmation":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","declined","expired"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["status","expiresAt"],"additionalProperties":false},{"type":"null"}]},"mySession":{"anyOf":[{"type":"object","properties":{"sessionId":{"type":"string"},"phase":{"type":"string"},"code":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time"}},"required":["sessionId","phase","code","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["ref","title","status","createdAt","sentAt","completedAt","dueAt","format","documents","recipients","files","preparedBy","sentBy","confirmation","mySession"],"additionalProperties":false}},"required":["status","request"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"confirmation_required"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"signToConfirm":{"type":"boolean"}},"required":["status","url","expiresAt","signToConfirm"],"additionalProperties":false}]}}}},"202":{"description":"Accepted, but the person has to say yes first: the answer is confirmation_required, with a link for them.","content":{"application/json":{"schema":{"type":"object","anyOf":[{"type":"object","properties":{"status":{"type":"string","const":"sent"},"request":{"type":"object","properties":{"ref":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["pdf","asice"]},{"type":"null"}]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"pages":{"type":["integer","null"]}},"required":["id","name","pages"],"additionalProperties":false}},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"type":"string","enum":["signer","viewer"]},"step":{"type":["integer","null"]},"channel":{"type":"string","enum":["email","sms","both"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"status":{"type":"string","enum":["waiting","sent","opened","signed","declined","bounced"]},"isYou":{"type":"boolean"},"openedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","email","phone","role","step","channel","language","status","isYou","openedAt","signedAt","declinedAt"],"additionalProperties":false}},"files":{"type":"object","properties":{"signed":{"type":"boolean"},"certificate":{"type":"boolean"},"copies":{"type":"integer"}},"required":["signed","certificate","copies"],"additionalProperties":false},"preparedBy":{"type":["string","null"]},"sentBy":{"type":["string","null"]},"confirmation":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","declined","expired"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["status","expiresAt"],"additionalProperties":false},{"type":"null"}]},"mySession":{"anyOf":[{"type":"object","properties":{"sessionId":{"type":"string"},"phase":{"type":"string"},"code":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time"}},"required":["sessionId","phase","code","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["ref","title","status","createdAt","sentAt","completedAt","dueAt","format","documents","recipients","files","preparedBy","sentBy","confirmation","mySession"],"additionalProperties":false}},"required":["status","request"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","const":"confirmation_required"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"signToConfirm":{"type":"boolean"}},"required":["status","url","expiresAt","signToConfirm"],"additionalProperties":false}]}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests/{ref}/sign":{"post":{"operationId":"sign_myself","summary":"Sign it myself","description":"Ask the person's phone for their own signature on this request (Smart-ID). The answer is a 4-digit code to show them exactly as given — their phone shows the same code and they enter PIN2 — or a link they open to sign. Only the person can sign; this never signs for them.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","anyOf":[{"type":"object","properties":{"mode":{"type":"string","const":"push"},"sessionId":{"type":"string"},"code":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time"},"next":{"type":"string"}},"required":["mode","sessionId","code","expiresAt","next"],"additionalProperties":false},{"type":"object","properties":{"mode":{"type":"string","const":"link"},"url":{"type":"string","format":"uri"},"next":{"type":"string"}},"required":["mode","url","next"],"additionalProperties":false}]}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests/{ref}":{"get":{"operationId":"get_status","summary":"Request status","description":"One signing request: its documents, each person's status, and which signed files exist.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["pdf","asice"]},{"type":"null"}]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"pages":{"type":["integer","null"]}},"required":["id","name","pages"],"additionalProperties":false}},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"type":"string","enum":["signer","viewer"]},"step":{"type":["integer","null"]},"channel":{"type":"string","enum":["email","sms","both"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"status":{"type":"string","enum":["waiting","sent","opened","signed","declined","bounced"]},"isYou":{"type":"boolean"},"openedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","email","phone","role","step","channel","language","status","isYou","openedAt","signedAt","declinedAt"],"additionalProperties":false}},"files":{"type":"object","properties":{"signed":{"type":"boolean"},"certificate":{"type":"boolean"},"copies":{"type":"integer"}},"required":["signed","certificate","copies"],"additionalProperties":false},"preparedBy":{"type":["string","null"]},"sentBy":{"type":["string","null"]},"confirmation":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","declined","expired"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["status","expiresAt"],"additionalProperties":false},{"type":"null"}]},"mySession":{"anyOf":[{"type":"object","properties":{"sessionId":{"type":"string"},"phase":{"type":"string"},"code":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time"}},"required":["sessionId","phase","code","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["ref","title","status","createdAt","sentAt","completedAt","dueAt","format","documents","recipients","files","preparedBy","sentBy","confirmation","mySession"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests/{ref}/files":{"get":{"operationId":"get_signed_file","summary":"Get the signed file","description":"Download links (valid for one hour) for the signed file, the signing certificate and the signed copies, when they exist.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"signed":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","name","expiresAt"],"additionalProperties":false},{"type":"null"}]},"certificate":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","name","expiresAt"],"additionalProperties":false},{"type":"null"}]},"copies":{"anyOf":[{"type":"object","properties":{"url":{"type":"string","format":"uri"},"name":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}},"required":["url","name","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["signed","certificate","copies"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/verify":{"post":{"operationId":"verify_file","summary":"Check a signed file","description":"Check a signed PDF or signed package (.asice, .edoc): who signed, when, and whether each signature is qualified. Nothing is kept. Over MCP the file is base64 (at most about 700 KB).","parameters":[{"name":"X-File-Name","in":"header","required":false,"schema":{"type":"string","maxLength":300},"description":"The file's name, percent-encoded UTF-8."}],"requestBody":{"required":true,"description":"The file's bytes, at most 47185920 bytes.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"format":{"type":"string","enum":["pdf","package"]},"files":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]},"trust":{"type":"string","enum":["eu_lists","test"]},"signatures":{"type":"array","items":{"type":"object","properties":{"signerName":{"type":["string","null"]},"organisation":{"type":["string","null"]},"country":{"type":["string","null"]},"signedAt":{"type":["string","null"]},"kind":{"type":"string"},"status":{"type":"string"},"problem":{"type":["string","null"]},"covers":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["signerName","organisation","country","signedAt","kind","status","problem","covers"],"additionalProperties":false}}},"required":["format","files","trust","signatures"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"413":{"description":"The file is larger than OkoSign accepts (`too_large`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"415":{"description":"The body is not a file of a type this operation takes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests/{ref}/remind":{"post":{"operationId":"remind_signer","summary":"Remind a signer","description":"Send one person who has not signed yet a reminder, with an optional short note. At most once an hour per person.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"recipientId":{"type":"integer","exclusiveMinimum":0},"note":{"type":"string","maxLength":1000}},"required":["recipientId"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["pdf","asice"]},{"type":"null"}]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"pages":{"type":["integer","null"]}},"required":["id","name","pages"],"additionalProperties":false}},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"type":"string","enum":["signer","viewer"]},"step":{"type":["integer","null"]},"channel":{"type":"string","enum":["email","sms","both"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"status":{"type":"string","enum":["waiting","sent","opened","signed","declined","bounced"]},"isYou":{"type":"boolean"},"openedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","email","phone","role","step","channel","language","status","isYou","openedAt","signedAt","declinedAt"],"additionalProperties":false}},"files":{"type":"object","properties":{"signed":{"type":"boolean"},"certificate":{"type":"boolean"},"copies":{"type":"integer"}},"required":["signed","certificate","copies"],"additionalProperties":false},"preparedBy":{"type":["string","null"]},"sentBy":{"type":["string","null"]},"confirmation":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","declined","expired"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["status","expiresAt"],"additionalProperties":false},{"type":"null"}]},"mySession":{"anyOf":[{"type":"object","properties":{"sessionId":{"type":"string"},"phase":{"type":"string"},"code":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time"}},"required":["sessionId","phase","code","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["ref","title","status","createdAt","sentAt","completedAt","dueAt","format","documents","recipients","files","preparedBy","sentBy","confirmation","mySession"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/requests/{ref}/cancel":{"post":{"operationId":"cancel_request","summary":"Cancel a request","description":"Call off a sent request. Everyone who has it is told. Signatures already made stay on record.","parameters":[{"name":"ref","in":"path","required":true,"schema":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ref":{"type":"string","pattern":"^OKS-\\d{4}-\\d{4,}$"},"title":{"type":"string"},"status":{"type":"string","enum":["draft","sent","completed","declined","voided","expired"]},"createdAt":{"type":"string","format":"date-time"},"sentAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"dueAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"format":{"anyOf":[{"type":"string","enum":["pdf","asice"]},{"type":"null"}]},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"pages":{"type":["integer","null"]}},"required":["id","name","pages"],"additionalProperties":false}},"recipients":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"email":{"type":["string","null"]},"phone":{"type":["string","null"]},"role":{"type":"string","enum":["signer","viewer"]},"step":{"type":["integer","null"]},"channel":{"type":"string","enum":["email","sms","both"]},"language":{"type":"string","enum":["lv","et","lt","en","ru"]},"status":{"type":"string","enum":["waiting","sent","opened","signed","declined","bounced"]},"isYou":{"type":"boolean"},"openedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","email","phone","role","step","channel","language","status","isYou","openedAt","signedAt","declinedAt"],"additionalProperties":false}},"files":{"type":"object","properties":{"signed":{"type":"boolean"},"certificate":{"type":"boolean"},"copies":{"type":"integer"}},"required":["signed","certificate","copies"],"additionalProperties":false},"preparedBy":{"type":["string","null"]},"sentBy":{"type":["string","null"]},"confirmation":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["pending","approved","declined","expired"]},"expiresAt":{"type":"string","format":"date-time"}},"required":["status","expiresAt"],"additionalProperties":false},{"type":"null"}]},"mySession":{"anyOf":[{"type":"object","properties":{"sessionId":{"type":"string"},"phase":{"type":"string"},"code":{"anyOf":[{"type":"string","pattern":"^\\d{4}$"},{"type":"null"}]},"expiresAt":{"type":"string","format":"date-time"}},"required":["sessionId","phase","code","expiresAt"],"additionalProperties":false},{"type":"null"}]}},"required":["ref","title","status","createdAt","sentAt","completedAt","dueAt","format","documents","recipients","files","preparedBy","sentBy","confirmation","mySession"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/sender-names":{"get":{"operationId":"list_sender_names","summary":"Sender names","description":"The sender names invites may come from. A new name needs the person's approval on okosign.com.","responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"names":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"kind":{"type":"string","enum":["person","team","custom"]},"isDefault":{"type":"boolean"}},"required":["name","kind","isDefault"],"additionalProperties":false}},"verifiedName":{"type":["string","null"]},"teamName":{"type":["string","null"]},"pending":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"createdAt":{"type":"string"}},"required":["id","name","status","createdAt"],"additionalProperties":false}},"approved":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"status":{"type":"string","enum":["pending","approved"]},"createdAt":{"type":"string"}},"required":["id","name","status","createdAt"],"additionalProperties":false}},"canApprove":{"type":"boolean","const":false},"approvalUrl":{"type":"string","format":"uri"}},"required":["names","verifiedName","teamName","pending","approved","canApprove","approvalUrl"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/webhooks":{"get":{"operationId":"webhooks_list","summary":"Webhook endpoints","description":"The webhook endpoints of this workspace and the events each one receives. Secrets are never shown again.","responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"endpoints":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","events","createdAt"],"additionalProperties":false}}},"required":["endpoints"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]},"post":{"operationId":"webhooks_create","summary":"Add a webhook endpoint","description":"Register an https address that receives request.signed, request.declined, request.completed or request.expired, signed the Standard Webhooks way. The secret is in this answer only.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["request.signed","request.declined","request.completed","request.expired"]}}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"Created. The answer describes what was made.","content":{"application/json":{"schema":{"type":"object","properties":{"endpoint":{"type":"object","properties":{"id":{"type":"integer"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"}},"required":["id","url","events","createdAt"],"additionalProperties":false},"secret":{"type":"string","pattern":"^whsec_"}},"required":["endpoint","secret"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/webhooks/{id}":{"delete":{"operationId":"webhooks_delete","summary":"Remove a webhook endpoint","description":"Stop sending to a webhook endpoint. Deliveries not yet made to it are dropped.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":2147483647}}],"responses":{"200":{"description":"The answer.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","const":true}},"required":["ok"],"additionalProperties":false}}}},"400":{"description":"The request is not valid. `field` names the first problem.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"No valid API key or access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"402":{"description":"Nothing left to use in this period. The person can add more on okosign.com.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"Not allowed: the connection, the role or the access to this request does not permit it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"Not found, or not visible to this caller.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"409":{"description":"The request is in a state that does not allow this, or the person has to confirm their identity first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"500":{"description":"Something went wrong on OkoSign's side (`server_error`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"Not available right now (signing, checking files, or OkoSign is busy). Try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"apiKey":[]},{"oauth2":["okosign"]}]}},"/files/{token}":{"get":{"operationId":"download_file","summary":"Download a signed file","description":"The link comes from get_signed_file and is valid for one hour. It is the credential: send no Authorization header.","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The file, as an attachment.","content":{"application/octet-stream":{"schema":{"type":"string","format":"binary"}}}},"404":{"description":"The link is unknown, has expired, or no longer reaches the file.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"Too many requests. Wait and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[]}}},"webhooks":{"request.signed":{"post":{"summary":"Event request.signed","description":"One person signed. `data.recipient` is that person. Request-level facts as of the first delivery attempt; call get_status for the current state. Signed the Standard Webhooks way. Answer with any 2xx status; anything else is retried on a schedule over about three days.","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unique per delivery; the same on every retry."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Seconds since the epoch, when this attempt was made."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}` under the endpoint's secret."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}},"responses":{"200":{"description":"Received."}}}},"request.declined":{"post":{"summary":"Event request.declined","description":"One person declined. `data.recipient` is that person. Request-level facts as of the first delivery attempt; call get_status for the current state. Signed the Standard Webhooks way. Answer with any 2xx status; anything else is retried on a schedule over about three days.","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unique per delivery; the same on every retry."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Seconds since the epoch, when this attempt was made."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}` under the endpoint's secret."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}},"responses":{"200":{"description":"Received."}}}},"request.completed":{"post":{"summary":"Event request.completed","description":"Everyone signed. `data.recipient` is null. Request-level facts as of the first delivery attempt; call get_status for the current state. Signed the Standard Webhooks way. Answer with any 2xx status; anything else is retried on a schedule over about three days.","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unique per delivery; the same on every retry."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Seconds since the epoch, when this attempt was made."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}` under the endpoint's secret."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}},"responses":{"200":{"description":"Received."}}}},"request.expired":{"post":{"summary":"Event request.expired","description":"The request ran out of time. `data.recipient` is null. Request-level facts as of the first delivery attempt; call get_status for the current state. Signed the Standard Webhooks way. Answer with any 2xx status; anything else is retried on a schedule over about three days.","parameters":[{"name":"webhook-id","in":"header","required":true,"schema":{"type":"string"},"description":"Unique per delivery; the same on every retry."},{"name":"webhook-timestamp","in":"header","required":true,"schema":{"type":"string"},"description":"Seconds since the epoch, when this attempt was made."},{"name":"webhook-signature","in":"header","required":true,"schema":{"type":"string"},"description":"`v1,` and the base64 HMAC-SHA256 of `{webhook-id}.{webhook-timestamp}.{body}` under the endpoint's secret."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookPayload"}}}},"responses":{"200":{"description":"Received."}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","bearerFormat":"oks_live_…"},"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://app.okosign.com/oauth/authorize","tokenUrl":"https://app.okosign.com/oauth/token","scopes":{"okosign":"Prepare, send and read signing requests for the person who connected."}}}}},"schemas":{"ErrorBody":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":true},"WebhookPayload":{"type":"object","properties":{"type":{"type":"string","enum":["request.signed","request.declined","request.completed","request.expired"]},"timestamp":{"type":"string","format":"date-time"},"data":{"type":"object","properties":{"ref":{"type":"string"},"title":{"type":"string"},"status":{"type":"string"},"signedCount":{"type":"integer"},"signerCount":{"type":"integer"},"completedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"recipient":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"role":{"type":"string"},"status":{"type":"string"},"signedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"declinedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["id","name","role","status","signedAt","declinedAt"],"additionalProperties":false},{"type":"null"}]}},"required":["ref","title","status","signedCount","signerCount","completedAt","recipient"],"additionalProperties":false}},"required":["type","timestamp","data"],"additionalProperties":false}}}}