{"openapi":"3.1.0","info":{"title":"CanUSign API","version":"1","description":"Create contracts from HTML or your own PDF, send signing links, receive webhooks and download the signed PDF. Every request needs an API key (`canu_` prefix) as Bearer token. Rate limit: 60 requests per minute per key; every authenticated response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` (ISO 8601)."},"externalDocs":{"url":"https://canusign.com/en/docs/api"},"servers":[{"url":"https://canusign.com"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/contracts":{"get":{"summary":"List contracts","parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","pending","pending_payment","fully_signed","cancelled"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Contracts of the key owner, newest first.","content":{"application/json":{"schema":{"type":"object","properties":{"contracts":{"type":"array","items":{"$ref":"#/components/schemas/ContractListItem"}},"pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"offset":{"type":"integer"},"hasMore":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid `status`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a contract","description":"From HTML (`content`) or from your own PDF (`document`) with signature fields placed in percent of the page, origin top left. Without `finalize: true` the contract is a draft and costs nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateContract"}}}},"responses":{"201":{"description":"Created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"contract":{"$ref":"#/components/schemas/CreatedContract"}}}}}},"400":{"description":"Invalid body. `details` lists field errors for `signatureFields` and `attachments`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Monthly document limit of the plan reached, `code: LIMIT_REACHED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitReached"}}}},"409":{"description":"Invalid `signers`: `code` is one of INVALID_EMAIL, INVALID_LEVEL, UNKNOWN_ROLE, QES_NOT_ENABLED, QES_ROLE_TAKEN, ALREADY_SIGNED, RATE_LIMITED.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Invalid `signers`: `code` is one of INVALID_EMAIL, INVALID_LEVEL, UNKNOWN_ROLE, QES_NOT_ENABLED, QES_ROLE_TAKEN, ALREADY_SIGNED, RATE_LIMITED. Also the rate limit, see RateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A signing link could not be sent. The contract was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contracts/{id}":{"parameters":[{"name":"id","in":"path","required":true,"description":"Contract ID or contract token.","schema":{"type":"string"}}],"get":{"summary":"Get a contract","responses":{"200":{"description":"The contract.","content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"$ref":"#/components/schemas/Contract"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Rename, retag, add signers or finalize a draft","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"title":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"finalize":{"const":true},"signers":{"type":"array","items":{"$ref":"#/components/schemas/SignerInput"}}}}}}},"responses":{"200":{"description":"The updated contract.","content":{"application/json":{"schema":{"type":"object","properties":{"contract":{"$ref":"#/components/schemas/Contract"}}}}}},"400":{"description":"Invalid body or nothing to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Monthly document limit of the plan reached, `code: LIMIT_REACHED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LimitReached"}}}},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`CONTRACT_SIGNED` (title or tags on a signed contract), `NOT_A_DRAFT` (finalize on a non-draft), or a signer error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Invalid `signers`: `code` is one of INVALID_EMAIL, INVALID_LEVEL, UNKNOWN_ROLE, QES_NOT_ENABLED, QES_ROLE_TAKEN, ALREADY_SIGNED, RATE_LIMITED. Also the rate limit, see RateLimited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"A signing link could not be sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a contract without signatures","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The contract has signatures, `code: CONTRACT_SIGNED`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"signatureCount":{"type":"integer"}}}]}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contracts/{id}/cancel":{"parameters":[{"name":"id","in":"path","required":true,"description":"Contract ID or contract token.","schema":{"type":"string"}}],"post":{"summary":"Cancel an open contract","description":"Status becomes `cancelled`, signatures stay. Cancelling a cancelled contract answers 200 again.","responses":{"200":{"description":"Cancelled.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"contract":{"$ref":"#/components/schemas/ContractSummary"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Fully signed, `code: CONTRACT_SIGNED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contracts/{id}/pdf":{"parameters":[{"name":"id","in":"path","required":true,"description":"Contract ID or contract token.","schema":{"type":"string"}}],"get":{"summary":"Download the signed PDF","description":"Contract, documents, attachments and audit certificate in one file. Every download after the first returns the stored bytes.","responses":{"200":{"description":"The signed PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Contract not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Not fully signed yet (`code: NOT_SIGNED`, with `status`), or a qualified signature is still being applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Timestamp failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contracts/from-template":{"get":{"deprecated":true,"summary":"Removed: templates","description":"Templates were removed from the product. Always answers 410.","responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"410":{"description":"Gone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gone"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"deprecated":true,"summary":"Removed: templates","description":"Templates were removed from the product. Always answers 410.","responses":{"401":{"$ref":"#/components/responses/Unauthorized"},"410":{"description":"Gone.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Gone"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/attachments":{"get":{"summary":"List attachment types","parameters":[{"name":"country","in":"query","description":"ISO 3166-1 alpha-2. Also returns types for any country.","schema":{"type":"string"}}],"responses":{"200":{"description":"Attachment types and their fields.","content":{"application/json":{"schema":{"type":"object","properties":{"attachments":{"type":"array","items":{"$ref":"#/components/schemas/AttachmentType"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks":{"get":{"summary":"List webhooks","responses":{"200":{"description":"Webhooks of the key owner.","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"summary":"Create a webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/WebhookEvent"}}}}}}},"responses":{"201":{"description":"Created. The secret is shown only here.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"const":true},"webhook":{"allOf":[{"$ref":"#/components/schemas/Webhook"},{"type":"object","properties":{"secret":{"type":"string","pattern":"^whsec_"}}}]}}}}}},"400":{"description":"Invalid URL or events.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"409":{"description":"More than 5 webhooks per account, `code: LIMIT_REACHED`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/webhooks/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"summary":"Get a webhook with its last 20 deliveries","responses":{"200":{"description":"The webhook.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"},"deliveries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"event":{"type":"string"},"statusCode":{"type":["integer","null"]},"success":{"type":"boolean"},"attempt":{"type":"integer"},"duration":{"type":["integer","null"]},"createdAt":{"type":"string","format":"date-time"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"summary":"Update a webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","minProperties":1,"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/WebhookEvent"}},"active":{"type":"boolean"}}}}}},"responses":{"200":{"description":"The updated webhook.","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"description":"Invalid body or nothing to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"summary":"Delete a webhook","responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Success"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Webhook not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"description":"Uncaught error, `code: INTERNAL_ERROR`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from the settings page, starts with `canu_`. 60 requests per minute per key."}},"responses":{"Unauthorized":{"description":"Missing or malformed Authorization header, or invalid or expired key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"More than 60 requests in the current minute, `code: RATE_LIMITED`.","headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds until reset."}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"details":{}}},"Success":{"type":"object","properties":{"success":{"const":true}}},"Gone":{"type":"object","properties":{"error":{"const":"gone"},"message":{"type":"string"}}},"LimitReached":{"allOf":[{"$ref":"#/components/schemas/Error"},{"type":"object","properties":{"documentsUsed":{"type":"integer"},"documentsLimit":{"type":"integer"}}}]},"ContractStatus":{"type":"string","enum":["draft","pending","pending_payment","fully_signed","cancelled"]},"WebhookEvent":{"type":"string","enum":["contract.created","contract.signed","contract.completed","contract.deleted","contract.cancelled","signer.invited"]},"SignerInput":{"type":"object","description":"With `email`, the signer gets a delivered link for the field label named by `label` (or `role`).","properties":{"role":{"type":"string"},"label":{"type":"string"},"email":{"type":"string","format":"email"},"level":{"type":"string","enum":["ses","qes"],"default":"ses"},"title":{"type":"string","maxLength":80,"description":"What the signer signs as, e.g. \"Managing Director\". Preset in the sign dialog and printed in the stamp under the name; the signer can change it."}}},"SignatureFieldInput":{"type":"object","description":"Placement only with a `document`: then `x` and `y` are required, in percent of the page, origin top left. Without a document the fields are appended below the HTML and any placement is an error. `type` other than `signature` needs a document. `label` names the signer and is required except on `text`. A `date` field shows the day its signer signs and needs a signature field with the same label. A `text` field prints `text` as is. An `input` field is filled in by its signer in the signing dialog, before the signature, and then printed like text; `text` is the value the dialog starts with, `optional: true` allows it empty, and it needs a signature field with the same label. At least one `signature` or `initials` field is required with a document.","properties":{"type":{"type":"string","enum":["signature","initials","date","text","input"],"default":"signature"},"label":{"type":"string"},"text":{"type":"string","maxLength":500,"description":"Required on `text` (up to 500 characters). Optional default on `input` (up to 200). Not allowed elsewhere."},"optional":{"type":"boolean","default":false,"description":"Only on `input`: the signer may leave the field empty."},"page":{"type":"integer","minimum":1,"default":1},"x":{"type":"number","minimum":0,"maximum":100},"y":{"type":"number","minimum":0,"maximum":100},"width":{"type":"number","exclusiveMinimum":0,"maximum":100,"description":"Default 25 (signature), 10 (initials), 18 (date), 25 (text, input)."},"height":{"type":"number","exclusiveMinimum":0,"maximum":100,"description":"Default 10 (signature), 4 (initials), 3.3 (date), 3 (text, input)."}}},"CreateContract":{"type":"object","properties":{"title":{"type":"string"},"content":{"type":"string","description":"HTML."},"language":{"type":"string","enum":["de","en","es","fr"],"default":"en"},"document":{"type":"object","required":["pdf"],"properties":{"name":{"type":"string"},"pdf":{"type":"string","description":"Base64 or data URL, at most 3 MB. Requires at least one signature field."}}},"signatureFields":{"type":"array","items":{"$ref":"#/components/schemas/SignatureFieldInput"}},"signaturesCentered":{"type":"boolean"},"signers":{"type":"array","items":{"$ref":"#/components/schemas/SignerInput"}},"tags":{"type":"array","items":{"type":"string"}},"finalize":{"type":"boolean"},"attachments":{"type":"array","description":"See GET /api/v1/attachments.","items":{"type":"object","required":["type","fields"],"properties":{"type":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"string"}}}}}}},"Signer":{"type":"object","description":"A delivered link per role, with its status instead of the link.","properties":{"id":{"type":"string"},"role":{"type":"string"},"email":{"type":"string"},"level":{"type":"string","enum":["ses","qes"]},"status":{"type":"string","enum":["created","sent","opened","signed"]},"sentAt":{"type":["string","null"],"format":"date-time"},"sendCount":{"type":"integer"},"openedAt":{"type":["string","null"],"format":"date-time"},"signedAt":{"type":["string","null"],"format":"date-time"}}},"ContractSummary":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string"},"title":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ContractStatus"}}},"CreatedContract":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string"},"title":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ContractStatus"},"language":{"type":"string"},"signUrl":{"type":["string","null"],"description":"Only while `pending`."},"requiresPayment":{"type":"boolean"},"publicId":{"type":"string"},"verifyUrl":{"type":["string","null"],"description":"`null` for drafts."},"signers":{"type":"array","items":{"$ref":"#/components/schemas/Signer"}},"createdAt":{"type":"string","format":"date-time"}}},"ContractListItem":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string"},"title":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ContractStatus"},"language":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signedAt":{"type":["string","null"],"format":"date-time"},"publicId":{"type":"string"},"verifyUrl":{"type":["string","null"]},"signatures":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"name":{"type":"string"},"signerName":{"type":["string","null"]},"signedAt":{"type":"string","format":"date-time"}}}},"signers":{"type":"array","items":{"$ref":"#/components/schemas/Signer"}}}},"Contract":{"type":"object","properties":{"id":{"type":"string"},"token":{"type":"string"},"title":{"type":["string","null"]},"status":{"$ref":"#/components/schemas/ContractStatus"},"language":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"signUrl":{"type":["string","null"],"description":"Only while `pending`."},"statusUrl":{"type":"string"},"pdfUrl":{"type":["string","null"],"description":"Only when `fully_signed`."},"publicId":{"type":"string"},"verifyUrl":{"type":["string","null"]},"finalPdf":{"type":["object","null"],"description":"SHA-256 of the stored PDF, `null` until it was built once.","properties":{"sha256":{"type":"string"},"storedAt":{"type":["string","null"],"format":"date-time"}}},"signatures":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"role":{"type":"string"},"name":{"type":"string"},"signerName":{"type":["string","null"]},"signedAt":{"type":"string","format":"date-time"},"deliveredLink":{"type":"boolean"}}}},"signers":{"type":"array","items":{"$ref":"#/components/schemas/Signer"}},"documents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"pages":{"type":"integer"},"order":{"type":"integer"}}}},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"signedAt":{"type":["string","null"],"format":"date-time"}}},"AttachmentType":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"country":{"type":"string","description":"ISO 3166-1 alpha-2 or 'any'."},"fields":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"label":{"type":"string"},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string"}},"example":{"type":"string"}}}}}},"Webhook":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEvent"}},"active":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}}}}