{ "openapi": "3.0.3", "info": { "title": "Closign API", "version": "1.0.0", "description": "Create documents for e-signature from your own software, send them in the order you choose, and download the signed PDF when everyone has signed. The API uses JSON over HTTPS and workspace API keys.\n\n## Getting started\n\nAPI access is included in the Team and Business plans. A workspace admin creates a key in **Settings → API keys** and chooses what it may do. The key is shown once; Closign keeps only a hash of it.\n\nCheck that the key works:\n\n```bash\ncurl https://closign.io/api/v1/me \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"\n```\n\n`GET /me` answers with the workspace, the key's permissions and your rate limit. Then create an envelope from a PDF or a template with `POST /envelopes`, send it, follow its status, and download the signed PDF once it's completed.\n\n## Authentication\n\nSend the key on every request as a bearer token in the `Authorization` header. Keys start with `cs_live_`.\n\nA key belongs to the workspace, not to a person. Envelopes it creates are owned by the admin who created the key, or by the workspace owner if that admin has left. The audit trail records that they were made through the API, with the key's name.\n\nEach key has one or more permissions:\n\n| Permission | Allows |\n|---|---|\n| `envelopes:read` | Listing and reading envelopes, downloading signed PDFs and audit certificates |\n| `envelopes:write` | Creating, sending, voiding and reminding envelopes |\n| `templates:read` | Listing and reading templates |\n\nRevoke a key in Settings → API keys and it stops working at once. Keep keys on your server: never put one in a web page or a mobile app.\n\n## Requests and responses\n\n- The base URL is `https://closign.io/api/v1`, over HTTPS only.\n- Send JSON with `Content-Type: application/json`. To upload a PDF as a file, use `multipart/form-data`; then `recipients`, `fields` and `variables` are JSON strings.\n- Answers are JSON, except the PDF downloads. One object is under `data`, a list is `data` plus pagination. Every object says what it is in `object`: `envelope`, `recipient` or `template`.\n- Times are UTC in ISO 8601, such as `2026-10-08T09:30:12Z`.\n- Envelope IDs start with `env_` and recipient IDs with `rcp_`. Templates are known by their slug, such as `quotation-acceptance`.\n\n## Errors\n\nEvery error has the same shape:\n\n```json\n{\n \"error\": {\n \"code\": \"validation_error\",\n \"message\": \"The recipients field is required.\",\n \"details\": { \"recipients\": [\"The recipients field is required.\"] }\n }\n}\n```\n\n`code` is stable: check it in your code. `message` is written for people and may change. `details` is there when there's more to say; for `validation_error` it lists each field with its problems.\n\n| Status | Meaning |\n|---|---|\n| 401 | No key, or a key that isn't valid |\n| 402 | The plan's document limit is reached |\n| 403 | The workspace can't use the API, or the key doesn't have the permission |\n| 404 | Not found, or not in this workspace |\n| 409 | The envelope's state doesn't allow it (yet) |\n| 422 | Something in the request isn't valid |\n| 429 | Too many requests |\n| 500 | Something went wrong on our side: safe to retry |\n\nEvery code is listed under Error codes, below.\n\n## Rate limits\n\nRequests are counted per workspace, all its keys together:\n\n| Plan | Requests a minute |\n|---|---|\n| Team | 60 |\n| Business | 300 |\n\nWithin that, a workspace can create 30 envelopes a minute. Every answer has the headers `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a 429 also has `Retry-After`, in seconds. An IP address that sends 30 requests in a minute with a missing or wrong key is blocked until the minute is up.\n\n## Idempotency\n\n`POST /envelopes` takes an `Idempotency-Key` header: any string up to 255 characters that's unique to the envelope you mean to create, such as a UUID or your own order number. If a request times out, send it again with the same key: within 24 hours you get the first answer again, with the header `Idempotent-Replayed: true`, instead of a second envelope.\n\n- The same key with a different request: 422 `idempotency_key_reused`.\n- The same key while the first request is still running: 409 `idempotency_in_progress`.\n- Only successful answers are kept. After an error, fix the request and send it again with the same key.\n\nKeys are per workspace.\n\n## Pagination\n\n`GET /envelopes` answers a page at a time: `per_page` (25 unless you ask for up to 100) and `page`. `meta.total` and `meta.last_page` say how many there are, and `links.next` is the next page's URL, or `null` on the last page.\n\n## Envelope status\n\n| Status | Meaning |\n|---|---|\n| `draft` | Not sent yet |\n| `sent` | Out for signing |\n| `expired` | Sent, but the signing links expired before everyone signed |\n| `changes_requested` | An approver asked for changes, so signing is paused |\n| `completed` | Everyone has signed and the signed PDF is ready |\n| `declined` | A signer declined |\n| `voided` | You voided it |\n\nThe signed PDF takes a few seconds to build after the last signature. Until it's ready the envelope stays `sent`, with every recipient `signed`, so `completed` always means the signed PDF can be downloaded. To follow progress, check `GET /envelopes/{id}` or list `GET /envelopes?status=completed`; once a minute is plenty.\n\nA recipient is `not_sent` while the envelope is a draft, `waiting` until it's their turn, then `sent`, `viewed`, and `signed` (an approver: `approved`), `declined` or `changes_requested`. `not_needed` means someone else in their signing group signed. A CC is `pending`, then `copied` once they're sent the signed copy.\n\n## Signing order\n\nGive each signer and approver a `routing_order`, starting at 1. Lower numbers go first, and recipients with the same number are emailed at the same time. The next number starts when everyone before it has finished. Give a `routing_order` to every signer and approver, or to none, and they go in list order.\n\nApprovers approve the document before the recipients after them; they fill in nothing. CCs are sent the signed PDF when it's completed.\n\n## Signing links and codes\n\nThe API never returns signing links or signing codes. Closign emails each recipient their own link when it's their turn, and confirms their email address with a one-time code before they sign.\n\n## Error codes\n\n| Code | Status | Meaning |\n|---|---|---|\n| `unauthenticated` | 401 | No API key in the `Authorization` header. |\n| `invalid_api_key` | 401 | The key isn't valid: mistyped, revoked or expired. |\n| `workspace_suspended` | 403 | The workspace is suspended, so its keys don't work. |\n| `plan_without_api` | 403 | The workspace's plan doesn't include API access. |\n| `no_active_member` | 403 | There's nobody active in the workspace for the key to act as. |\n| `missing_ability` | 403 | The key doesn't have the permission this endpoint needs; `details.required` names it. |\n| `forbidden` | 403 | Not allowed. |\n| `rate_limited` | 429 | Too many requests. Wait for the `Retry-After` seconds. |\n| `not_found` | 404 | No such endpoint, or no such envelope or template in this workspace. |\n| `method_not_allowed` | 405 | The endpoint doesn't take this HTTP method. |\n| `validation_error` | 422 | Something in the request isn't valid; `details` lists each field's problems. |\n| `http_error` | 4xx | Another HTTP error, such as a request that's too large (413). |\n| `server_error` | 500 | Something went wrong on our side. It's safe to retry; if it keeps happening, write to support@closign.io. |\n| `invalid_idempotency_key` | 422 | `Idempotency-Key` is empty or longer than 255 characters. |\n| `idempotency_key_reused` | 422 | This `Idempotency-Key` was already used for a different request. |\n| `idempotency_in_progress` | 409 | A request with this `Idempotency-Key` is still being processed. |\n| `unsupported_file_type` | 422 | The file isn't a PDF. |\n| `file_too_large` | 422 | The PDF is over the size limit. |\n| `pdf_encrypted` | 422 | The PDF is password-protected. Remove the password and send it again. |\n| `pdf_unreadable` | 422 | The PDF can't be read. Export it again as a standard PDF. |\n| `unknown_template` | 422 | There's no template with this `template_id`. |\n| `unknown_template_role` | 422 | A signer's `template_role` is missing or isn't one of the template's roles; `details.roles` lists them. |\n| `duplicate_template_role` | 422 | Two signers have the same `template_role`. |\n| `missing_template_roles` | 422 | One of the template's roles has no signer; `details.missing` lists them. |\n| `unknown_variables` | 422 | The template has no such variable; `details.unknown` lists them. |\n| `invalid_variables` | 422 | A value doesn't fit its variable's type or options; `details.invalid` lists them. |\n| `missing_variables` | 422 | A required variable has no value; `details.missing` lists them. |\n| `template_failed` | 422 or 500 | The document couldn't be made from the template. |\n| `missing_fields` | 422 | A signer has no field to fill in; `details.recipients` lists them. |\n| `plan_limit_reached` | 402 | The workspace has sent as many documents as its plan allows this month; the message says what to do, and `details.upgrade_url` links to the plans. |\n| `restricted_document` | 422 | The document looks like one the IT Act excludes from e-signing. Set `acknowledge_restricted` to send it anyway. |\n| `cannot_send` | 409 or 422 | The envelope can't be sent as it is; the message says why. |\n| `already_sent` | 409 | The envelope isn't a draft any more. |\n| `not_out_for_signing` | 409 | Only an envelope that's out for signing can be voided or reminded. |\n| `nobody_to_remind` | 409 | Everyone whose turn it is has already finished. |\n| `reminded_recently` | 429 | Everyone whose turn it is was reminded in the last hour. |\n| `not_completed` | 409 | The signed PDF is ready once the envelope is completed. |\n| `not_finished` | 409 | The audit certificate is ready once the envelope is completed, declined or voided. |", "contact": { "name": "Closign support", "email": "support@closign.io" } }, "servers": [ { "url": "https://closign.io/api/v1" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "The key itself." }, { "name": "Envelopes", "description": "Documents sent for signing: create, send, follow, void, remind and download." }, { "name": "Templates", "description": "The template library an envelope can be made from." } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Account" ], "summary": "Check a key", "description": "The key's workspace and plan, its permissions, who it acts as, and the rate limit. Any key can call it.", "x-errors": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://closign.io/api/v1/me \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "The key works.", "headers": { "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Me" } } }, "example": { "data": { "workspace": { "name": "Your company", "plan": "Team" }, "key": { "name": "CRM", "prefix": "cs_live_PhnU", "abilities": [ "envelopes:read", "envelopes:write", "templates:read" ] }, "acting_as": { "name": "Workspace admin", "email": "admin@example.com" }, "rate_limit": { "requests_per_minute": 60 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes": { "post": { "operationId": "createEnvelope", "tags": [ "Envelopes" ], "summary": "Create an envelope", "x-permission": "envelopes:write", "description": "Create an envelope from a PDF or a template, with its recipients. Send it straight away with `\"send\": true`, or keep it as a draft and send it later with `POST /envelopes/{id}/send`.\n\n**The document** is one of:\n\n- `file`: the PDF, as `multipart/form-data` (up to 25 MB);\n- `file_base64`: the PDF in base64, in JSON (up to about 23 MB), with its `file_name`;\n- `template_id`: one of the templates from `GET /templates`, filled in with `variables`.\n\nA PDF is checked by its content, and password-protected PDFs are refused.\n\n**Recipients** are a `signer` (fills in fields and signs), an `approver` (approves before the recipients after them, and fills in nothing) or a `cc` (is sent the signed copy). There's at least one signer. See Signing order for `routing_order`.\n\n**Fields** (for a PDF) say where each signer fills in. A field's position is in % of the page: `x` and `y` are its top-left corner, measured from the page's top-left, and `width` and `height` its size. `recipient_index` is the signer's position in `recipients`, counting from 0. To send, every signer needs at least one field.\n\n**From a template**, give every signer a `template_role` (a role's `key` or `name` from `GET /templates/{id}`, one signer per role) and fill in `variables` by name. The template places its own fields.\n\nSending checks what the app checks: the plan's document limit (402), and a document the IT Act excludes from e-signing (a will or a power of attorney, say) needs `acknowledge_restricted`. Creating and sending is all or nothing: when the send is refused, no envelope is kept.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeCreate" }, "examples": { "pdf": { "summary": "From a PDF, sent now", "value": { "title": "Master services agreement", "message": "Please review and sign by Friday.", "file_base64": "JVBERi0xLjMKMyAwIG9iago8PC9UeXBl…", "file_name": "services-agreement.pdf", "recipients": [ { "name": "Legal approver", "email": "legal@example.com", "role": "approver", "routing_order": 1 }, { "name": "Client signatory", "email": "client@example.com", "role": "signer", "routing_order": 2 }, { "name": "Our director", "email": "director@example.com", "role": "signer", "routing_order": 3 }, { "name": "Accounts", "email": "accounts@example.com", "role": "cc" } ], "fields": [ { "recipient_index": 1, "type": "signature", "page": 11, "x": 10, "y": 72, "width": 30, "height": 6 }, { "recipient_index": 1, "type": "date", "page": 11, "x": 10, "y": 80, "width": 20, "height": 3 }, { "recipient_index": 2, "type": "signature", "page": 11, "x": 55, "y": 72, "width": 30, "height": 6 } ], "send": true, "reminder_every_days": 2, "expires_in_days": 30 } }, "template": { "summary": "From a template, sent now", "value": { "template_id": "quotation-acceptance", "title": "Quotation Q-2026-114", "variables": { "quote_ref": "Q-2026-114 dated 28 September 2026", "scope": "Website redesign and six months of support", "timeline": "8 weeks from the advance", "fee_amount": "177000", "currency": "INR" }, "recipients": [ { "name": "Our director", "email": "director@example.com", "role": "signer", "template_role": "Supplier" }, { "name": "Client signatory", "email": "client@example.com", "role": "signer", "template_role": "Client" } ], "send": true } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/EnvelopeCreateMultipart" } } } }, "x-errors": [ "validation_error", "unsupported_file_type", "file_too_large", "pdf_encrypted", "pdf_unreadable", "unknown_template", "unknown_template_role", "duplicate_template_role", "missing_template_roles", "unknown_variables", "invalid_variables", "missing_variables", "template_failed", "missing_fields", "plan_limit_reached", "restricted_document", "cannot_send", "invalid_idempotency_key", "idempotency_key_reused", "idempotency_in_progress" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://closign.io/api/v1/envelopes \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\" \\\n -H \"Idempotency-Key: order-1042\" \\\n -F file=@services-agreement.pdf \\\n -F title=\"Master services agreement\" \\\n -F send=true \\\n -F 'recipients=[{\"name\":\"Legal approver\",\"email\":\"legal@example.com\",\"role\":\"approver\",\"routing_order\":1},{\"name\":\"Client signatory\",\"email\":\"client@example.com\",\"role\":\"signer\",\"routing_order\":2}]' \\\n -F 'fields=[{\"recipient_index\":1,\"type\":\"signature\",\"page\":11,\"x\":10,\"y\":72,\"width\":30,\"height\":6}]'" } ], "responses": { "201": { "description": "Created (and sent, with `send`).", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "env_01M4DCFF50MMEY085SAM4RXQYY", "object": "envelope", "title": "Master services agreement", "status": "sent", "message": "Please review and sign by Friday.", "source": "upload", "template_id": null, "pages": 11, "signing_order": "sequential", "reminder_every_days": 2, "expires_at": "2026-11-07T23:59:59Z", "void_reason": null, "created_at": "2026-10-08T09:30:12Z", "sent_at": "2026-10-08T09:30:13Z", "completed_at": null, "voided_at": null, "recipients": [ { "id": "rcp_01M4DCH9R0WTT0VT7XNH45ES50", "object": "recipient", "name": "Legal approver", "email": "legal@example.com", "role": "approver", "routing_order": 1, "status": "sent", "sent_at": "2026-10-08T09:30:13Z", "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCK4B0G4THVBMA661ZT2QG", "object": "recipient", "name": "Client signatory", "email": "client@example.com", "role": "signer", "routing_order": 2, "status": "waiting", "sent_at": null, "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCMYY0637M1DPK63THFQEG", "object": "recipient", "name": "Our director", "email": "director@example.com", "role": "signer", "routing_order": 3, "status": "waiting", "sent_at": null, "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCPSH0EF2CNVZWVJ7Z6KXY", "object": "recipient", "name": "Accounts", "email": "accounts@example.com", "role": "cc", "routing_order": null, "status": "pending", "sent_at": null, "viewed_at": null, "acted_at": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "402": { "description": "The plan's document limit is reached (sending only).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_limit_reached": { "value": { "error": { "code": "plan_limit_reached", "message": "You've sent 2400 documents this month, more than we expect on the Business plan. Please contact support and we'll sort it out quickly; your drafts are saved.", "details": { "upgrade_url": "https://closign.io/pricing" } } } } } } } }, "409": { "description": "The same `Idempotency-Key` is still being processed, or the envelope can't be sent as it is.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "idempotency_in_progress": { "value": { "error": { "code": "idempotency_in_progress", "message": "A request with this Idempotency-Key is still being processed. Try again in a moment." } } } } } } }, "422": { "description": "Something in the request isn't valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_error": { "value": { "error": { "code": "validation_error", "message": "Give every signer and approver a routing_order, or none of them (then they sign in list order).", "details": { "recipients": [ "Give every signer and approver a routing_order, or none of them (then they sign in list order)." ] } } } }, "missing_fields": { "value": { "error": { "code": "missing_fields", "message": "Every signer needs at least one field to fill in. No fields yet for: Our director.", "details": { "recipients": [ "rcp_01M4DCMYY0637M1DPK63THFQEG" ] } } } }, "pdf_encrypted": { "value": { "error": { "code": "pdf_encrypted", "message": "This PDF is password-protected. Remove the password and send it again." } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "get": { "operationId": "listEnvelopes", "tags": [ "Envelopes" ], "summary": "List envelopes", "x-permission": "envelopes:read", "description": "The workspace's envelopes, newest first, a page at a time. Filter by `status`.", "parameters": [ { "name": "status", "in": "query", "required": false, "style": "form", "explode": false, "description": "One or more statuses, separated by commas.", "schema": { "type": "array", "items": { "type": "string", "enum": [ "draft", "sent", "expired", "changes_requested", "completed", "declined", "voided" ] } }, "example": "sent,completed" }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } } ], "x-errors": [ "validation_error" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl \"https://closign.io/api/v1/envelopes?status=sent,completed&per_page=50\" \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "A page of envelopes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "links", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Envelope" } }, "links": { "$ref": "#/components/schemas/PageLinks" }, "meta": { "$ref": "#/components/schemas/PageMeta" } } }, "example": { "data": [ { "id": "env_01M4DCFF50MMEY085SAM4RXQYY", "object": "envelope", "title": "Master services agreement", "status": "completed", "message": "Please review and sign by Friday.", "source": "upload", "template_id": null, "pages": 11, "signing_order": "sequential", "reminder_every_days": 2, "expires_at": "2026-11-07T23:59:59Z", "void_reason": null, "created_at": "2026-10-08T09:30:12Z", "sent_at": "2026-10-08T09:30:13Z", "completed_at": "2026-10-09T14:05:41Z", "voided_at": null, "recipients": [ { "id": "rcp_01M4DCH9R0WTT0VT7XNH45ES50", "object": "recipient", "name": "Legal approver", "email": "legal@example.com", "role": "approver", "routing_order": 1, "status": "approved", "sent_at": "2026-10-08T09:30:13Z", "viewed_at": "2026-10-08T10:02:55Z", "acted_at": "2026-10-08T10:06:20Z", "decline_reason": null, "comment": "Clause 7 reads well now." }, { "id": "rcp_01M4DCK4B0G4THVBMA661ZT2QG", "object": "recipient", "name": "Client signatory", "email": "client@example.com", "role": "signer", "routing_order": 2, "status": "signed", "sent_at": "2026-10-08T10:06:21Z", "viewed_at": "2026-10-08T16:40:02Z", "acted_at": "2026-10-08T16:44:37Z", "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCMYY0637M1DPK63THFQEG", "object": "recipient", "name": "Our director", "email": "director@example.com", "role": "signer", "routing_order": 3, "status": "signed", "sent_at": "2026-10-08T16:44:38Z", "viewed_at": "2026-10-09T14:01:10Z", "acted_at": "2026-10-09T14:05:39Z", "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCPSH0EF2CNVZWVJ7Z6KXY", "object": "recipient", "name": "Accounts", "email": "accounts@example.com", "role": "cc", "routing_order": null, "status": "copied", "sent_at": "2026-10-09T14:05:41Z", "viewed_at": null, "acted_at": null } ] } ], "links": { "first": "https://closign.io/api/v1/envelopes?page=1", "last": "https://closign.io/api/v1/envelopes?page=4", "prev": null, "next": "https://closign.io/api/v1/envelopes?page=2" }, "meta": { "current_page": 1, "from": 1, "last_page": 4, "links": [], "path": "https://closign.io/api/v1/envelopes", "per_page": 25, "to": 25, "total": 87 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "An unknown status, or a page size over 100.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_error": { "value": { "error": { "code": "validation_error", "message": "status is one or more of draft, sent, expired, changes_requested, completed, declined, voided, separated by commas.", "details": { "status.0": [ "status is one or more of draft, sent, expired, changes_requested, completed, declined, voided, separated by commas." ] } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}": { "get": { "operationId": "getEnvelope", "tags": [ "Envelopes" ], "summary": "Get an envelope", "x-permission": "envelopes:read", "description": "An envelope with its recipients and where each one is.", "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "x-errors": [ "not_found" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://closign.io/api/v1/envelopes/env_01M4DCFF50MMEY085SAM4RXQYY \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "The envelope.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "env_01M4DCFF50MMEY085SAM4RXQYY", "object": "envelope", "title": "Master services agreement", "status": "completed", "message": "Please review and sign by Friday.", "source": "upload", "template_id": null, "pages": 11, "signing_order": "sequential", "reminder_every_days": 2, "expires_at": "2026-11-07T23:59:59Z", "void_reason": null, "created_at": "2026-10-08T09:30:12Z", "sent_at": "2026-10-08T09:30:13Z", "completed_at": "2026-10-09T14:05:41Z", "voided_at": null, "recipients": [ { "id": "rcp_01M4DCH9R0WTT0VT7XNH45ES50", "object": "recipient", "name": "Legal approver", "email": "legal@example.com", "role": "approver", "routing_order": 1, "status": "approved", "sent_at": "2026-10-08T09:30:13Z", "viewed_at": "2026-10-08T10:02:55Z", "acted_at": "2026-10-08T10:06:20Z", "decline_reason": null, "comment": "Clause 7 reads well now." }, { "id": "rcp_01M4DCK4B0G4THVBMA661ZT2QG", "object": "recipient", "name": "Client signatory", "email": "client@example.com", "role": "signer", "routing_order": 2, "status": "signed", "sent_at": "2026-10-08T10:06:21Z", "viewed_at": "2026-10-08T16:40:02Z", "acted_at": "2026-10-08T16:44:37Z", "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCMYY0637M1DPK63THFQEG", "object": "recipient", "name": "Our director", "email": "director@example.com", "role": "signer", "routing_order": 3, "status": "signed", "sent_at": "2026-10-08T16:44:38Z", "viewed_at": "2026-10-09T14:01:10Z", "acted_at": "2026-10-09T14:05:39Z", "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCPSH0EF2CNVZWVJ7Z6KXY", "object": "recipient", "name": "Accounts", "email": "accounts@example.com", "role": "cc", "routing_order": null, "status": "copied", "sent_at": "2026-10-09T14:05:41Z", "viewed_at": null, "acted_at": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}/send": { "post": { "operationId": "sendEnvelope", "tags": [ "Envelopes" ], "summary": "Send a draft", "x-permission": "envelopes:write", "description": "Send a draft now, and optionally change its message, reminders and expiry. Every signer needs a field, and the plan's document limit applies.", "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendEnvelope" }, "example": { "message": "Please review and sign by Friday.", "expires_in_days": 30 } } } }, "x-errors": [ "not_found", "already_sent", "missing_fields", "plan_limit_reached", "restricted_document", "cannot_send", "validation_error" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://closign.io/api/v1/envelopes/env_01M4DCFF50MMEY085SAM4RXQYY/send \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"message\":\"Please review and sign by Friday.\",\"expires_in_days\":30}'" } ], "responses": { "200": { "description": "Sent.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "env_01M4DCFF50MMEY085SAM4RXQYY", "object": "envelope", "title": "Master services agreement", "status": "sent", "message": "Please review and sign by Friday.", "source": "upload", "template_id": null, "pages": 11, "signing_order": "sequential", "reminder_every_days": 2, "expires_at": "2026-11-07T23:59:59Z", "void_reason": null, "created_at": "2026-10-08T09:30:12Z", "sent_at": "2026-10-08T09:30:13Z", "completed_at": null, "voided_at": null, "recipients": [ { "id": "rcp_01M4DCH9R0WTT0VT7XNH45ES50", "object": "recipient", "name": "Legal approver", "email": "legal@example.com", "role": "approver", "routing_order": 1, "status": "sent", "sent_at": "2026-10-08T09:30:13Z", "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCK4B0G4THVBMA661ZT2QG", "object": "recipient", "name": "Client signatory", "email": "client@example.com", "role": "signer", "routing_order": 2, "status": "waiting", "sent_at": null, "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCMYY0637M1DPK63THFQEG", "object": "recipient", "name": "Our director", "email": "director@example.com", "role": "signer", "routing_order": 3, "status": "waiting", "sent_at": null, "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCPSH0EF2CNVZWVJ7Z6KXY", "object": "recipient", "name": "Accounts", "email": "accounts@example.com", "role": "cc", "routing_order": null, "status": "pending", "sent_at": null, "viewed_at": null, "acted_at": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The plan's document limit is reached.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "plan_limit_reached": { "value": { "error": { "code": "plan_limit_reached", "message": "You've sent 2400 documents this month, more than we expect on the Business plan. Please contact support and we'll sort it out quickly; your drafts are saved.", "details": { "upgrade_url": "https://closign.io/pricing" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "It's not a draft.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "already_sent": { "value": { "error": { "code": "already_sent", "message": "This document has already been sent. Its status is sent.", "details": { "status": "sent" } } } } } } } }, "422": { "description": "It can't be sent as it is.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_fields": { "value": { "error": { "code": "missing_fields", "message": "Every signer needs at least one field to fill in. No fields yet for: Our director.", "details": { "recipients": [ "rcp_01M4DCMYY0637M1DPK63THFQEG" ] } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}/void": { "post": { "operationId": "voidEnvelope", "tags": [ "Envelopes" ], "summary": "Void an envelope", "x-permission": "envelopes:write", "description": "Cancel an envelope that's out for signing (`sent`, `expired` or `changes_requested`). The signing links stop working, and everyone who was emailed a link is told, with your reason.", "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidEnvelope" }, "example": { "reason": "Sending a corrected version." } } } }, "x-errors": [ "not_found", "not_out_for_signing", "validation_error" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://closign.io/api/v1/envelopes/env_01M4DCFF50MMEY085SAM4RXQYY/void \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"Sending a corrected version.\"}'" } ], "responses": { "200": { "description": "Voided.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Envelope" } } }, "example": { "data": { "id": "env_01M4DCFF50MMEY085SAM4RXQYY", "object": "envelope", "title": "Master services agreement", "status": "voided", "message": "Please review and sign by Friday.", "source": "upload", "template_id": null, "pages": 11, "signing_order": "sequential", "reminder_every_days": 2, "expires_at": "2026-11-07T23:59:59Z", "void_reason": "Sending a corrected version.", "created_at": "2026-10-08T09:30:12Z", "sent_at": "2026-10-08T09:30:13Z", "completed_at": null, "voided_at": "2026-10-08T11:15:00Z", "recipients": [ { "id": "rcp_01M4DCH9R0WTT0VT7XNH45ES50", "object": "recipient", "name": "Legal approver", "email": "legal@example.com", "role": "approver", "routing_order": 1, "status": "sent", "sent_at": "2026-10-08T09:30:13Z", "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCK4B0G4THVBMA661ZT2QG", "object": "recipient", "name": "Client signatory", "email": "client@example.com", "role": "signer", "routing_order": 2, "status": "waiting", "sent_at": null, "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCMYY0637M1DPK63THFQEG", "object": "recipient", "name": "Our director", "email": "director@example.com", "role": "signer", "routing_order": 3, "status": "waiting", "sent_at": null, "viewed_at": null, "acted_at": null, "decline_reason": null, "comment": null }, { "id": "rcp_01M4DCPSH0EF2CNVZWVJ7Z6KXY", "object": "recipient", "name": "Accounts", "email": "accounts@example.com", "role": "cc", "routing_order": null, "status": "pending", "sent_at": null, "viewed_at": null, "acted_at": null } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "It isn't out for signing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_out_for_signing": { "value": { "error": { "code": "not_out_for_signing", "message": "Only a document that's out for signing can be voided. This one is completed.", "details": { "status": "completed" } } } } } } } }, "422": { "description": "No reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "validation_error": { "value": { "error": { "code": "validation_error", "message": "Give a reason. Signers who got the email are told why the document was voided.", "details": { "reason": [ "Give a reason. Signers who got the email are told why the document was voided." ] } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}/remind": { "post": { "operationId": "remindEnvelope", "tags": [ "Envelopes" ], "summary": "Remind", "x-permission": "envelopes:write", "description": "Email the signing link again to everyone whose turn it is. Each recipient can be reminded once an hour; the answer says who was reminded and who was skipped.", "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "x-errors": [ "not_found", "not_out_for_signing", "nobody_to_remind", "reminded_recently" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://closign.io/api/v1/envelopes/env_01M4DCFF50MMEY085SAM4RXQYY/remind \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "Reminded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/RemindResult" } } }, "example": { "data": { "reminded": [ { "id": "rcp_01M4DCK4B0G4THVBMA661ZT2QG", "email": "client@example.com" } ], "skipped": [] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not out for signing, or nobody to remind.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_out_for_signing": { "value": { "error": { "code": "not_out_for_signing", "message": "Only a document that's out for signing can be reminded. This one is draft.", "details": { "status": "draft" } } } }, "nobody_to_remind": { "value": { "error": { "code": "nobody_to_remind", "message": "Nobody can be reminded right now: everyone whose turn it is has finished." } } } } } } }, "429": { "description": "Everyone whose turn it is was reminded in the last hour, or too many requests (`rate_limited`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "reminded_recently": { "value": { "error": { "code": "reminded_recently", "message": "Everyone whose turn it is was reminded in the last 60 minutes. Try again later." } } } } } } } } } }, "/envelopes/{id}/document": { "get": { "operationId": "downloadDocument", "tags": [ "Envelopes" ], "summary": "Download the signed PDF", "x-permission": "envelopes:read", "description": "The signed PDF, with the audit certificate at the end, once the envelope is `completed`.", "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "x-errors": [ "not_found", "not_completed" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -o services-agreement-signed.pdf https://closign.io/api/v1/envelopes/env_01M4DCFF50MMEY085SAM4RXQYY/document \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "The signed PDF.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not completed yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_completed": { "value": { "error": { "code": "not_completed", "message": "The signed PDF is ready once everyone has signed. This document is sent.", "details": { "status": "sent" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}/audit": { "get": { "operationId": "downloadAudit", "tags": [ "Envelopes" ], "summary": "Download the audit certificate", "x-permission": "envelopes:read", "description": "The audit certificate on its own: who did what and when, with IP addresses and the document's fingerprints. Ready once the envelope is `completed`, `declined` or `voided`.", "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "x-errors": [ "not_found", "not_finished" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -o services-agreement-certificate.pdf https://closign.io/api/v1/envelopes/env_01M4DCFF50MMEY085SAM4RXQYY/audit \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "The audit certificate.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not finished yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_finished": { "value": { "error": { "code": "not_finished", "message": "The audit certificate is ready once the document is completed, declined or voided. This document is sent.", "details": { "status": "sent" } } } } } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates": { "get": { "operationId": "listTemplates", "tags": [ "Templates" ], "summary": "List templates", "x-permission": "templates:read", "description": "The templates an envelope can be made from, with who signs them (`roles`) and what fills them in (`variables`).", "x-errors": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://closign.io/api/v1/templates \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "The templates.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } } } }, "example": { "data": [ { "id": "quotation-acceptance", "object": "template", "title": "Quotation acceptance", "description": "The client accepts a quotation or estimate so work can start: scope, price, GST, advance and timeline.", "category": "business", "roles": [ { "key": "party_1", "name": "Supplier", "witness": false }, { "key": "party_2", "name": "Client", "witness": false } ], "variables": [ { "name": "quote_ref", "label": "Quotation number / date", "type": "string", "required": true, "hint": "e.g. \"Q-2026-114 dated 28 September 2026\"" }, { "name": "scope", "label": "Work or goods quoted", "type": "text", "required": true }, { "name": "timeline", "label": "Delivery / completion", "type": "string", "required": true }, { "name": "fee_amount", "label": "Amount", "type": "money", "required": true }, { "name": "currency", "label": "Currency", "type": "choice", "required": true, "default": "INR", "options": [ "INR", "USD", "EUR", "GBP" ] }, { "name": "advance", "label": "Advance", "type": "money", "required": false } ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates/{id}": { "get": { "operationId": "getTemplate", "tags": [ "Templates" ], "summary": "Get a template", "x-permission": "templates:read", "description": "One template: its roles, for each signer's `template_role`, and its variables, for `variables`.", "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "x-errors": [ "not_found" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://closign.io/api/v1/templates/quotation-acceptance \\\n -H \"Authorization: Bearer $CLOSIGN_API_KEY\"" } ], "responses": { "200": { "description": "The template.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Template" } } }, "example": { "data": { "id": "quotation-acceptance", "object": "template", "title": "Quotation acceptance", "description": "The client accepts a quotation or estimate so work can start: scope, price, GST, advance and timeline.", "category": "business", "roles": [ { "key": "party_1", "name": "Supplier", "witness": false }, { "key": "party_2", "name": "Client", "witness": false } ], "variables": [ { "name": "quote_ref", "label": "Quotation number / date", "type": "string", "required": true, "hint": "e.g. \"Q-2026-114 dated 28 September 2026\"" }, { "name": "scope", "label": "Work or goods quoted", "type": "text", "required": true }, { "name": "timeline", "label": "Delivery / completion", "type": "string", "required": true }, { "name": "fee_amount", "label": "Amount", "type": "money", "required": true }, { "name": "currency", "label": "Currency", "type": "choice", "required": true, "default": "INR", "options": [ "INR", "USD", "EUR", "GBP" ] }, { "name": "advance", "label": "Advance", "type": "money", "required": false } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "cs_live_…", "description": "A workspace API key from Settings → API keys." } }, "parameters": { "EnvelopeId": { "name": "id", "in": "path", "required": true, "description": "The envelope's ID.", "schema": { "type": "string", "pattern": "^env_[0-9A-HJKMNP-TV-Z]{26}$" }, "example": "env_01M4DCFF50MMEY085SAM4RXQYY" }, "TemplateId": { "name": "id", "in": "path", "required": true, "description": "The template's ID.", "schema": { "type": "string", "pattern": "^[a-z0-9-]+$" }, "example": "quotation-acceptance" }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Retry safely: the same key within 24 hours gets the first answer again instead of a second envelope.", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "order-1042" } }, "headers": { "X-RateLimit-Limit": { "description": "Requests a minute for this workspace.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left this minute.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait.", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` when this is the first answer to an earlier request with the same `Idempotency-Key`.", "schema": { "type": "string", "enum": [ "true" ] } } }, "responses": { "Unauthorized": { "description": "No key, or a key that isn't valid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "invalid_api_key": { "value": { "error": { "code": "invalid_api_key", "message": "This API key isn't valid. It may have been revoked. A workspace admin can make a new one in Settings → API keys." } } } } } } }, "Forbidden": { "description": "The workspace can't use the API, or the key doesn't have this endpoint's permission.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "missing_ability": { "value": { "error": { "code": "missing_ability", "message": "This API key doesn't have the envelopes:write permission. A workspace admin can make a key that has it in Settings → API keys.", "details": { "required": "envelopes:write" } } } }, "plan_without_api": { "value": { "error": { "code": "plan_without_api", "message": "API access isn't included in this workspace's plan. Available on the Team plan. See plans to upgrade." } } } } } } }, "NotFound": { "description": "No such envelope or template in this workspace.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "not_found": { "value": { "error": { "code": "not_found", "message": "Not found. Check the URL and the ID." } } } } } } }, "RateLimited": { "description": "Too many requests.", "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "rate_limited": { "value": { "error": { "code": "rate_limited", "message": "Too many requests. Your plan allows 60 API requests a minute for this workspace. Try again in 42 seconds." } } } } } } } }, "schemas": { "Envelope": { "type": "object", "description": "A document sent, or to be sent, for signing.", "required": [ "id", "object", "title", "status", "message", "source", "template_id", "pages", "signing_order", "reminder_every_days", "expires_at", "void_reason", "created_at", "sent_at", "completed_at", "voided_at", "recipients" ], "properties": { "id": { "type": "string", "pattern": "^env_[0-9A-HJKMNP-TV-Z]{26}$", "example": "env_01M4DCFF50MMEY085SAM4RXQYY", "description": "`env_` and 26 characters." }, "object": { "type": "string", "enum": [ "envelope" ] }, "title": { "type": "string", "example": "Master services agreement" }, "status": { "type": "string", "enum": [ "draft", "sent", "expired", "changes_requested", "completed", "declined", "voided" ], "description": "See Envelope status." }, "message": { "type": "string", "nullable": true, "description": "Your message in the signing request email." }, "source": { "type": "string", "enum": [ "upload", "template", "ai" ], "description": "Made from a PDF, from a template, or drafted with AI in the app." }, "template_id": { "type": "string", "nullable": true, "description": "The template it was made from." }, "pages": { "type": "integer", "nullable": true }, "signing_order": { "type": "string", "enum": [ "sequential", "parallel" ], "description": "`parallel` when everyone signs at once (one `routing_order` for all), otherwise `sequential`." }, "reminder_every_days": { "type": "integer", "description": "Automatic reminders every this many days; 0 means off." }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the signing links expire; `null` if they don't." }, "void_reason": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When the signed PDF was ready." }, "voided_at": { "type": "string", "format": "date-time", "nullable": true }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Signers and approvers in routing order, then CCs." } } }, "Recipient": { "type": "object", "description": "A signer, an approver or a CC. Signing links and codes are never part of it.", "required": [ "id", "object", "name", "email", "role", "routing_order", "status", "sent_at", "viewed_at", "acted_at" ], "properties": { "id": { "type": "string", "pattern": "^rcp_[0-9A-HJKMNP-TV-Z]{26}$", "example": "rcp_01M4DCK4B0G4THVBMA661ZT2QG", "description": "`rcp_` and 26 characters." }, "object": { "type": "string", "enum": [ "recipient" ] }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email" }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ] }, "routing_order": { "type": "integer", "nullable": true, "description": "`null` for a CC." }, "status": { "type": "string", "enum": [ "not_sent", "waiting", "sent", "viewed", "signed", "approved", "declined", "changes_requested", "not_needed", "pending", "copied" ], "description": "See Envelope status." }, "sent_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When their signing request, or for a CC the signed copy, was emailed." }, "viewed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When they first opened the document." }, "acted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "When they signed, approved, declined or asked for changes." }, "decline_reason": { "type": "string", "nullable": true, "description": "Signers and approvers only: why they declined." }, "comment": { "type": "string", "nullable": true, "description": "Signers and approvers only: an approver's note with their approval, or the changes they asked for." } } }, "Template": { "type": "object", "description": "A template an envelope can be made from.", "required": [ "id", "object", "title", "description", "category", "roles", "variables" ], "properties": { "id": { "type": "string", "example": "quotation-acceptance", "description": "The template's slug." }, "object": { "type": "string", "enum": [ "template" ] }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "nullable": true }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateRole" }, "description": "Who signs it: each signer's `template_role` is one of these." }, "variables": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateVariable" }, "description": "What fills it in, by `name`." } } }, "TemplateRole": { "type": "object", "required": [ "key", "name", "witness" ], "properties": { "key": { "type": "string", "example": "party_2" }, "name": { "type": "string", "example": "Client" }, "witness": { "type": "boolean", "description": "Signs as a witness." } } }, "TemplateVariable": { "type": "object", "required": [ "name", "label", "type", "required" ], "properties": { "name": { "type": "string", "example": "fee_amount" }, "label": { "type": "string", "example": "Amount" }, "type": { "type": "string", "enum": [ "string", "text", "date", "integer", "money", "choice" ], "description": "`date`: YYYY-MM-DD (5 March 2026 and 05/03/2026 work too); `money`: a positive amount such as 177000; `integer`: a whole number; `choice`: one of `options`; `string` and `text`: up to 1,000 characters." }, "required": { "type": "boolean" }, "default": { "description": "Used when no value is given." }, "options": { "type": "array", "items": { "type": "string" }, "description": "The values a `choice` takes." }, "hint": { "type": "string", "description": "An example of what to fill in." } } }, "Me": { "type": "object", "required": [ "workspace", "key", "acting_as", "rate_limit" ], "properties": { "workspace": { "type": "object", "required": [ "name", "plan" ], "properties": { "name": { "type": "string" }, "plan": { "type": "string", "example": "Team" } } }, "key": { "type": "object", "required": [ "name", "prefix", "abilities" ], "properties": { "name": { "type": "string" }, "prefix": { "type": "string", "description": "The key's first characters, as Settings → API keys shows them.", "example": "cs_live_PhnU" }, "abilities": { "type": "array", "items": { "type": "string", "enum": [ "envelopes:read", "envelopes:write", "templates:read" ] } } } }, "acting_as": { "type": "object", "required": [ "name", "email" ], "description": "Who the key acts as: envelopes it creates are theirs.", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "rate_limit": { "type": "object", "required": [ "requests_per_minute" ], "properties": { "requests_per_minute": { "type": "integer", "example": 60 } } } } }, "RemindResult": { "type": "object", "required": [ "reminded", "skipped" ], "properties": { "reminded": { "type": "array", "items": { "type": "object", "required": [ "id", "email" ], "properties": { "id": { "type": "string", "pattern": "^rcp_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string", "format": "email" } } } }, "skipped": { "type": "array", "description": "Reminded less than an hour ago.", "items": { "type": "object", "required": [ "id", "email", "reason" ], "properties": { "id": { "type": "string", "pattern": "^rcp_[0-9A-HJKMNP-TV-Z]{26}$" }, "email": { "type": "string", "format": "email" }, "reason": { "type": "string", "enum": [ "reminded_recently" ] } } } } } }, "PageLinks": { "type": "object", "required": [ "first", "last", "prev", "next" ], "properties": { "first": { "type": "string", "format": "uri" }, "last": { "type": "string", "format": "uri" }, "prev": { "type": "string", "format": "uri", "nullable": true }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "`null` on the last page." } } }, "PageMeta": { "type": "object", "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ], "properties": { "current_page": { "type": "integer" }, "from": { "type": "integer", "nullable": true }, "last_page": { "type": "integer" }, "links": { "type": "array", "description": "Links for page buttons.", "items": { "type": "object" } }, "path": { "type": "string", "format": "uri" }, "per_page": { "type": "integer" }, "to": { "type": "integer", "nullable": true }, "total": { "type": "integer" } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable, for programs to check. Every code is listed under Error codes.", "example": "validation_error" }, "message": { "type": "string", "description": "For people; may change." }, "details": { "type": "object", "additionalProperties": true, "description": "More about it, when there's more: for `validation_error`, each field with its problems." } } } } }, "EnvelopeCreate": { "type": "object", "required": [ "recipients" ], "description": "One of `file_base64` or `template_id` (or `file`, in multipart).", "properties": { "title": { "type": "string", "maxLength": 255, "description": "Defaults to the file's name or the template's title." }, "message": { "type": "string", "maxLength": 2000, "description": "Your message in the signing request email." }, "file_base64": { "type": "string", "format": "byte", "description": "The PDF in base64; a `data:` URI works too. Up to about 23 MB of PDF." }, "file_name": { "type": "string", "maxLength": 255, "description": "The PDF's file name, with `file_base64`." }, "template_id": { "type": "string", "maxLength": 100, "description": "Make it from this template (`GET /templates`) instead of a PDF." }, "variables": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "description": "With `template_id`: the template's variables, by name." }, "letterhead": { "type": "boolean", "description": "With `template_id`: put the workspace's letterhead on it. Defaults to the template's setting." }, "initials": { "type": "boolean", "description": "With `template_id`: signers initial every page. Defaults to the template's setting." }, "recipients": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/RecipientInput" } }, "fields": { "type": "array", "maxItems": 500, "items": { "$ref": "#/components/schemas/FieldInput" }, "description": "For a PDF: where each signer fills in." }, "send": { "type": "boolean", "default": false, "description": "Send it now. Otherwise it's a draft, sent with `POST /envelopes/{id}/send`." }, "expires_in_days": { "type": "integer", "enum": [ 0, 7, 14, 30, 60, 90 ], "description": "The signing links expire after this many days; 0 means never. Defaults to the workspace's setting." }, "reminder_every_days": { "type": "integer", "enum": [ 0, 1, 2, 3, 5, 7 ], "description": "Remind whoever's turn it is every this many days; 0 means off. Defaults to the workspace's setting." }, "acknowledge_restricted": { "type": "boolean", "description": "Send it even if it looks like a document the IT Act excludes from e-signing (`restricted_document`)." } } }, "EnvelopeCreateMultipart": { "type": "object", "required": [ "file", "recipients" ], "description": "`multipart/form-data`, to upload the PDF as a file. The other fields are as in JSON; `recipients` and `fields` are JSON strings, and booleans are `true` or `false`.", "properties": { "file": { "type": "string", "format": "binary", "description": "The PDF, up to 25 MB." }, "title": { "type": "string", "maxLength": 255 }, "message": { "type": "string", "maxLength": 2000 }, "recipients": { "type": "string", "description": "The `recipients` array, as a JSON string." }, "fields": { "type": "string", "description": "The `fields` array, as a JSON string." }, "send": { "type": "boolean" }, "expires_in_days": { "type": "integer", "enum": [ 0, 7, 14, 30, 60, 90 ] }, "reminder_every_days": { "type": "integer", "enum": [ 0, 1, 2, 3, 5, 7 ] }, "acknowledge_restricted": { "type": "boolean" } } }, "RecipientInput": { "type": "object", "required": [ "name", "email", "role" ], "properties": { "name": { "type": "string", "maxLength": 255 }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "role": { "type": "string", "enum": [ "signer", "approver", "cc" ], "description": "`signer` fills in fields and signs; `approver` approves before the recipients after them; `cc` is sent the signed copy." }, "routing_order": { "type": "integer", "minimum": 1, "maximum": 50, "description": "Signers and approvers: lower goes first, equal at the same time. Give it to all of them or none (then list order)." }, "template_role": { "type": "string", "maxLength": 120, "description": "With `template_id`, for each signer: a role's `key` or `name`." } } }, "FieldInput": { "type": "object", "required": [ "recipient_index", "type", "page", "x", "y", "width", "height" ], "properties": { "recipient_index": { "type": "integer", "minimum": 0, "description": "The signer's position in `recipients`, counting from 0." }, "type": { "type": "string", "enum": [ "signature", "initials", "initials_box", "text", "fullname", "email", "phone", "company", "title", "address", "date", "time", "checkbox", "number", "textarea", "dropdown", "radio" ], "description": "`title` is the signer's job title." }, "page": { "type": "integer", "minimum": 1 }, "x": { "type": "number", "minimum": 0, "maximum": 100, "description": "The left edge, in % of the page's width." }, "y": { "type": "number", "minimum": 0, "maximum": 100, "description": "The top edge, in % of the page's height from the top." }, "width": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "description": "In % of the page's width; `x` + `width` is at most 100." }, "height": { "type": "number", "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "description": "In % of the page's height; `y` + `height` is at most 100." }, "label": { "type": "string", "maxLength": 255 }, "required": { "type": "boolean", "default": true }, "options": { "type": "array", "maxItems": 30, "items": { "type": "string", "maxLength": 100 }, "description": "For `dropdown` and `radio`: at least two choices." } } }, "SendEnvelope": { "type": "object", "properties": { "message": { "type": "string", "maxLength": 2000, "description": "Replaces the message in the signing request email." }, "expires_in_days": { "type": "integer", "enum": [ 0, 7, 14, 30, 60, 90 ] }, "reminder_every_days": { "type": "integer", "enum": [ 0, 1, 2, 3, 5, 7 ] }, "acknowledge_restricted": { "type": "boolean" } } }, "VoidEnvelope": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 1000, "description": "Everyone who was emailed a signing link is told." } } } } }, "x-error-codes": { "unauthenticated": { "status": "401", "description": "No API key in the `Authorization` header." }, "invalid_api_key": { "status": "401", "description": "The key isn't valid: mistyped, revoked or expired." }, "workspace_suspended": { "status": "403", "description": "The workspace is suspended, so its keys don't work." }, "plan_without_api": { "status": "403", "description": "The workspace's plan doesn't include API access." }, "no_active_member": { "status": "403", "description": "There's nobody active in the workspace for the key to act as." }, "missing_ability": { "status": "403", "description": "The key doesn't have the permission this endpoint needs; `details.required` names it." }, "forbidden": { "status": "403", "description": "Not allowed." }, "rate_limited": { "status": "429", "description": "Too many requests. Wait for the `Retry-After` seconds." }, "not_found": { "status": "404", "description": "No such endpoint, or no such envelope or template in this workspace." }, "method_not_allowed": { "status": "405", "description": "The endpoint doesn't take this HTTP method." }, "validation_error": { "status": "422", "description": "Something in the request isn't valid; `details` lists each field's problems." }, "http_error": { "status": "4xx", "description": "Another HTTP error, such as a request that's too large (413)." }, "server_error": { "status": "500", "description": "Something went wrong on our side. It's safe to retry; if it keeps happening, write to support@closign.io." }, "invalid_idempotency_key": { "status": "422", "description": "`Idempotency-Key` is empty or longer than 255 characters." }, "idempotency_key_reused": { "status": "422", "description": "This `Idempotency-Key` was already used for a different request." }, "idempotency_in_progress": { "status": "409", "description": "A request with this `Idempotency-Key` is still being processed." }, "unsupported_file_type": { "status": "422", "description": "The file isn't a PDF." }, "file_too_large": { "status": "422", "description": "The PDF is over the size limit." }, "pdf_encrypted": { "status": "422", "description": "The PDF is password-protected. Remove the password and send it again." }, "pdf_unreadable": { "status": "422", "description": "The PDF can't be read. Export it again as a standard PDF." }, "unknown_template": { "status": "422", "description": "There's no template with this `template_id`." }, "unknown_template_role": { "status": "422", "description": "A signer's `template_role` is missing or isn't one of the template's roles; `details.roles` lists them." }, "duplicate_template_role": { "status": "422", "description": "Two signers have the same `template_role`." }, "missing_template_roles": { "status": "422", "description": "One of the template's roles has no signer; `details.missing` lists them." }, "unknown_variables": { "status": "422", "description": "The template has no such variable; `details.unknown` lists them." }, "invalid_variables": { "status": "422", "description": "A value doesn't fit its variable's type or options; `details.invalid` lists them." }, "missing_variables": { "status": "422", "description": "A required variable has no value; `details.missing` lists them." }, "template_failed": { "status": "422 or 500", "description": "The document couldn't be made from the template." }, "missing_fields": { "status": "422", "description": "A signer has no field to fill in; `details.recipients` lists them." }, "plan_limit_reached": { "status": "402", "description": "The workspace has sent as many documents as its plan allows this month; the message says what to do, and `details.upgrade_url` links to the plans." }, "restricted_document": { "status": "422", "description": "The document looks like one the IT Act excludes from e-signing. Set `acknowledge_restricted` to send it anyway." }, "cannot_send": { "status": "409 or 422", "description": "The envelope can't be sent as it is; the message says why." }, "already_sent": { "status": "409", "description": "The envelope isn't a draft any more." }, "not_out_for_signing": { "status": "409", "description": "Only an envelope that's out for signing can be voided or reminded." }, "nobody_to_remind": { "status": "409", "description": "Everyone whose turn it is has already finished." }, "reminded_recently": { "status": "429", "description": "Everyone whose turn it is was reminded in the last hour." }, "not_completed": { "status": "409", "description": "The signed PDF is ready once the envelope is completed." }, "not_finished": { "status": "409", "description": "The audit certificate is ready once the envelope is completed, declined or voided." } } }