{ "openapi": "3.1.0", "info": { "title": "Signkoi API", "version": "2026-11-14", "summary": "Create, send and track e-signature envelopes, use templates and receive webhooks.", "description": "The Signkoi REST API. Authenticate with an API key (`Authorization: Bearer `), send JSON, and receive JSON. Guides: https://signkoi.com/developers", "contact": { "name": "Signkoi support", "email": "support@signkoi.com", "url": "https://signkoi.com/contact" }, "termsOfService": "https://signkoi.com/terms" }, "externalDocs": { "description": "Developer docs", "url": "https://signkoi.com/developers" }, "servers": [ { "url": "https://signkoi.com/api", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Account", "description": "Who the API key belongs to, its scopes, plan and usage." }, { "name": "Envelopes", "description": "An envelope is one or more PDFs sent to recipients for signature. Create, update, send, remind, void and track them." }, { "name": "Recipients", "description": "Manage the people on an envelope, resend invitations and create signing URLs for embedded signing." }, { "name": "Files", "description": "Download the original PDF, the signed PDF and the certificate of completion." }, { "name": "Templates", "description": "Reusable documents with roles and fields. Create an envelope from a template by filling its roles." }, { "name": "Webhooks", "description": "Get notified when envelopes and recipients change. Deliveries are signed with your endpoint secret." } ], "paths": { "/v1/me": { "get": { "tags": [ "Account" ], "operationId": "getMe", "summary": "Retrieve the account", "description": "Returns the account the API key belongs to and the key itself (name, scopes, expiry). Works with any key; `plan` and `usage` are included only when the key has the `account:read` scope. A good first call to check your key.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "The account.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" }, "example": { "object": "account", "id": "1842", "name": "Rina Koh", "email": "rina@acme.example", "locale": "en", "timezone": "Europe/London", "api_key": { "id": "311", "name": "CRM integration", "scopes": [ "envelopes:read", "envelopes:write", "account:read" ], "expires_at": null }, "plan": "pro", "usage": { "documents_this_period": 37, "document_limit": 200 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes": { "get": { "tags": [ "Envelopes" ], "operationId": "listEnvelopes", "summary": "List envelopes", "description": "Envelopes you own, newest first. Fields are not included; retrieve an envelope to get them.", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "parameters": [ { "name": "status", "in": "query", "description": "Only envelopes in this status (public names only; anything else is a 422 with `param` `status`).", "schema": { "$ref": "#/components/schemas/EnvelopeStatus" }, "example": "sent" }, { "name": "search", "in": "query", "description": "Matches the title.", "schema": { "type": "string" } }, { "name": "created_after", "in": "query", "description": "ISO 8601 date or date-time (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "created_before", "in": "query", "description": "ISO 8601 date or date-time (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "template_id", "in": "query", "description": "Only envelopes created from this template.", "schema": { "type": "string", "format": "uuid" } }, { "name": "metadata", "in": "query", "style": "deepObject", "explode": true, "description": "Exact metadata match, e.g. `metadata[crm_deal_id]=D-10492`. Several keys must all match.", "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "example": { "crm_deal_id": "D-10492" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of envelopes.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeList" }, "example": { "object": "list", "data": [ { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z" } ], "page": 1, "per_page": 20, "total": 1, "has_more": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Invalid filter, e.g. an unknown `status` (`validation_failed`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The selected status is invalid.", "param": "status", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Envelopes" ], "operationId": "createEnvelope", "summary": "Create an envelope", "description": "Creates an envelope from one or more PDFs, optionally with recipients, fields and metadata, and sends it right away with `send: true`. Upload the files as multipart (`file` or `files[]`) or inline as base64 in JSON. If you pass recipients but no fields, a signature box is placed on the last page for the first signer. Counts against your plan's monthly document allowance (402 `plan_limit` when it is used up); requests rejected by validation use no quota, and if anything fails after the upload the envelope is removed and the quota refunded. If `send` is true and the envelope is not ready (for example a signer without a signature field), nothing is kept and you get a 422 with the reason as `code`.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvelopeRequest" }, "example": { "title": "Consulting agreement — Acme Ltd", "files": [ { "name": "agreement.pdf", "content_base64": "JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGggNiAwIFI…" } ], "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "recipients": [ { "key": "client", "name": "Maya Patel", "email": "maya@example.com", "verification": "email_otp" }, { "name": "Jonas Weber", "email": "jonas@example.com", "role": "cc", "routing_order": 2, "language": "de" } ], "fields": [ { "recipient_key": "client", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06 }, { "recipient_key": "client", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04 } ], "metadata": { "crm_deal_id": "D-10492" }, "expires_in_days": 30, "reminders": { "delay_days": 2, "frequency_days": 3 }, "send": true } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CreateEnvelopeMultipart" }, "encoding": { "files[]": { "contentType": "application/pdf" }, "file": { "contentType": "application/pdf" } } } } }, "responses": { "201": { "description": "The created envelope (with fields).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "Idempotent-Replayed": { "$ref": "#/components/headers/Idempotent-Replayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "422": { "description": "Invalid request (`validation_failed`), a file problem (`file_required`, `file_conflict`, `too_many_files`, `invalid_file`, `invalid_base64`, `file_not_pdf`, `invalid_pdf`, `invalid_json`; `param` is `file`, `files`, `files.N` or `files.N.content_base64`), or with `send: true` a send check (`no_recipients`, `missing_recipient_details`, `unassigned_fields`, `missing_signature_field`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_not_pdf", "message": "Only PDF files can be uploaded.", "param": "files.0", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}": { "get": { "tags": [ "Envelopes" ], "operationId": "getEnvelope", "summary": "Retrieve an envelope", "description": "The envelope with its recipients and fields. Field values are included once the envelope is completed. Envelopes that are not yours return 404. Field ids change whenever the fields are replaced, so don't store them long-term.", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "responses": { "200": { "description": "The envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Envelopes" ], "operationId": "updateEnvelope", "summary": "Update an envelope", "description": "Change the title, message, expiry or reminders of a draft (409 `envelope_not_draft` otherwise), or the metadata of any envelope. Metadata is merged: keys you send are set, keys set to `null` are removed, others are kept; `metadata: null` clears it. `message: null` clears subject and body; `expires_in_days: null` removes the expiry.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateEnvelopeRequest" }, "example": { "metadata": { "crm_stage": "contract_sent", "old_key": null } } } } }, "responses": { "200": { "description": "The updated envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not a draft (`envelope_not_draft`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "envelope_not_draft", "message": "Only draft envelopes can be changed. Void it instead.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Envelopes" ], "operationId": "deleteEnvelope", "summary": "Delete a draft", "description": "Permanently deletes a draft envelope. Sent envelopes cannot be deleted (409 `envelope_not_draft`); void them instead.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not a draft (`envelope_not_draft`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "envelope_not_draft", "message": "Only draft envelopes can be changed. Void it instead.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/recipients": { "put": { "tags": [ "Recipients" ], "operationId": "replaceEnvelopeRecipients", "summary": "Replace recipients", "description": "Sets the complete list of recipients of a draft. Pass `id` to keep an existing recipient; recipients you leave out are deleted together with their fields.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceRecipientsRequest" }, "example": { "recipients": [ { "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "name": "Maya Patel", "email": "maya@example.com", "verification": "email_otp" }, { "name": "Jonas Weber", "email": "jonas@example.com", "role": "cc", "routing_order": 2 } ] } } } }, "responses": { "200": { "description": "The envelope with its new recipients.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "draft", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "pending", "language": "en", "verification": "email_otp", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": null, "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": null, "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not a draft (`envelope_not_draft`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "envelope_not_draft", "message": "Only draft envelopes can be changed. Void it instead.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/fields": { "put": { "tags": [ "Envelopes" ], "operationId": "replaceEnvelopeFields", "summary": "Replace fields", "description": "Sets the complete list of fields of a draft. Every field is recreated, so field ids change on each call. Coordinates are fractions (0–1) of the page, origin top-left. Every field needs a `recipient_id`; signature, initials, date and input fields must belong to a `signer` or `in_person_signer`.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceFieldsRequest" }, "example": { "fields": [ { "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06 }, { "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "text", "page": 1, "x": 0.12, "y": 0.3, "width": 0.35, "height": 0.04, "label": "Company number", "required": false } ] } } } }, "responses": { "200": { "description": "The envelope with its new fields.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "draft", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "pending", "language": "en", "verification": "email_otp", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": null, "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": null, "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not a draft (`envelope_not_draft`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "envelope_not_draft", "message": "Only draft envelopes can be changed. Void it instead.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/send": { "post": { "tags": [ "Envelopes" ], "operationId": "sendEnvelope", "summary": "Send an envelope", "description": "Sends a draft: the first recipients in the routing order are invited by email. Fails with 422 and a `code` when the envelope is not ready: `no_recipients`, `missing_recipient_details`, `missing_signature_field`, `unassigned_fields` or `expired`.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The sent envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not a draft (`envelope_not_draft`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "envelope_not_draft", "message": "Only draft envelopes can be changed. Void it instead.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "422": { "description": "The envelope is not ready to send: `no_recipients`, `missing_recipient_details`, `unassigned_fields`, `missing_signature_field` or `expired`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "missing_signature_field", "message": "Maya Patel needs at least one signature field.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/void": { "post": { "tags": [ "Envelopes" ], "operationId": "voidEnvelope", "summary": "Void an envelope", "description": "Cancels an envelope that is out for signature. Recipients who still had something to do are told by email, with your reason. Only `sent` envelopes can be voided.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VoidEnvelopeRequest" }, "example": { "reason": "Terms changed; a new version follows." } } } }, "responses": { "200": { "description": "The voided envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "voided", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": "2026-11-14T12:00:00Z", "void_reason": "Terms changed; a new version follows.", "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not out for signature (`envelope_not_sent`; expired envelopes count as not sent).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "envelope_not_sent", "message": "This envelope is not out for signature.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/remind": { "post": { "tags": [ "Envelopes" ], "operationId": "remindEnvelope", "summary": "Send a reminder", "description": "Emails the invitation again to every recipient whose turn it is (in-person signers excluded). Only for `sent` envelopes. Limited to 6 calls a minute per account (429 `rate_limited` with `Retry-After`).", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not out for signature (`envelope_not_sent`), or nobody can be reminded (`nobody_to_remind`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "nobody_to_remind", "message": "There is nobody to remind right now.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "description": "More than 6 reminders a minute (`rate_limited`), or your key's rate limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Slow down and retry after the Retry-After header.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/recipients/{rid}": { "patch": { "tags": [ "Recipients" ], "operationId": "updateEnvelopeRecipient", "summary": "Correct a recipient", "description": "Fixes a recipient's details while the envelope is out for signature and the recipient has not finished. Changing the email issues a new signing link (the old one stops working) and re-sends the invitation if it is their turn.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "$ref": "#/components/parameters/RecipientId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateRecipientRequest" }, "example": { "email": "maya.patel@example.com" } } } }, "responses": { "200": { "description": "The envelope with the corrected recipient.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya.patel@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not out for signature (`envelope_not_sent`) or the recipient has finished (`recipient_finished`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "recipient_finished", "message": "This recipient has already finished.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/recipients/{rid}/resend": { "post": { "tags": [ "Recipients" ], "operationId": "resendEnvelopeRecipient", "summary": "Resend the invitation", "description": "Emails the invitation again to one recipient whose turn it is. Limited to 10 calls a minute per account.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "$ref": "#/components/parameters/RecipientId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "Not possible right now: `envelope_not_sent`, `recipient_not_active` (not their turn yet), `recipient_finished` or `recipient_in_person` (in-person signers get no email).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "recipient_not_active", "message": "It is not this recipient's turn yet.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "description": "More than 10 resends a minute (`rate_limited`), or your key's rate limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Slow down and retry after the Retry-After header.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/recipients/{rid}/signing-url": { "post": { "tags": [ "Recipients" ], "operationId": "createRecipientSigningUrl", "summary": "Create a signing URL", "description": "Returns a URL that opens the signing page for this recipient, for embedded or in-person signing in your own app. Only for the recipient whose turn it is (409 `not_recipients_turn` otherwise). Each call is recorded in the audit trail. Never send this URL to anyone but the recipient.", "security": [ { "bearerAuth": [ "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "$ref": "#/components/parameters/RecipientId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The signing URL.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SigningUrl" }, "example": { "object": "signing_url", "url": "https://signkoi.com/s/8kQ2…", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is not out for signature (`envelope_not_sent`), or it is not this recipient's turn (`not_recipients_turn`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "not_recipients_turn", "message": "It is not this recipient's turn to sign.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/audit-trail": { "get": { "tags": [ "Envelopes" ], "operationId": "getEnvelopeAuditTrail", "summary": "Retrieve the audit trail", "description": "Every recorded event of the envelope, oldest first — `document.created`, `envelope.sent`, `recipient.sent`, `recipient.viewed`, `recipient.completed`, `envelope.completed` and so on. `actor` is the person who acted, or `null` for system events. IP addresses and verification codes are never included.", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "The audit trail.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventList" }, "example": { "object": "list", "data": [ { "object": "audit_event", "event": "document.created", "actor": { "name": "Rina Koh", "email": "rina@acme.example" }, "recipient_id": null, "created_at": "2026-11-14T09:30:05Z" }, { "object": "audit_event", "event": "envelope.sent", "actor": { "name": "Rina Koh", "email": "rina@acme.example" }, "recipient_id": null, "created_at": "2026-11-14T09:30:12Z" }, { "object": "audit_event", "event": "recipient.viewed", "actor": { "name": "Maya Patel", "email": "maya@example.com" }, "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "created_at": "2026-11-15T13:58:01Z" } ], "page": 1, "per_page": 20, "total": 3, "has_more": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/files/original": { "get": { "tags": [ "Files" ], "operationId": "downloadOriginalFile", "summary": "Download the original PDF", "description": "The PDF as uploaded (several files merged into one), named `.pdf`.", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "responses": { "200": { "description": "The PDF.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"…\"`", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/files/signed": { "get": { "tags": [ "Files" ], "operationId": "downloadSignedFile", "summary": "Download the signed PDF", "description": "The completed, digitally sealed PDF with every signature and value, named `<title> (signed).pdf`. 404 `file_not_ready` until the envelope is completed.", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "responses": { "200": { "description": "The signed PDF.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"…\"`", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No such envelope (`resource_missing`), or it is not completed yet (`file_not_ready`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_not_ready", "message": "The signed PDF is available once everyone has signed.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/envelopes/{id}/files/certificate": { "get": { "tags": [ "Files" ], "operationId": "downloadCertificate", "summary": "Download the certificate of completion", "description": "The certificate of completion with the audit trail, named `<title> (certificate).pdf`. 404 `file_not_ready` until the envelope is completed.", "security": [ { "bearerAuth": [ "envelopes:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "responses": { "200": { "description": "The certificate PDF.", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"…\"`", "schema": { "type": "string" } }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "No such envelope (`resource_missing`), or it is not completed yet (`file_not_ready`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_not_ready", "message": "The certificate is available once everyone has signed.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/templates": { "get": { "tags": [ "Templates" ], "operationId": "listTemplates", "summary": "List templates", "description": "Your templates and the ones your team shares with you, most recently updated first.", "security": [ { "bearerAuth": [ "templates:read" ] } ], "parameters": [ { "name": "search", "in": "query", "description": "Matches the title.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of templates.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateList" }, "example": { "object": "list", "data": [ { "object": "template", "id": "3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16", "title": "Mutual NDA", "description": "Two-party non-disclosure agreement.", "roles": [ { "role_name": "Client", "role": "signer", "routing_order": 1 }, { "role_name": "Company", "role": "signer", "routing_order": 2 } ], "field_count": 6, "page_count": 2, "shared_with_team": true, "uses": 41, "created_at": "2026-08-02T11:20:00Z", "updated_at": "2026-10-28T16:45:13Z" } ], "page": 1, "per_page": 20, "total": 1, "has_more": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/templates/{id}": { "get": { "tags": [ "Templates" ], "operationId": "getTemplate", "summary": "Retrieve a template", "description": "The template with its roles and fields. Fields reference roles by `role_name`.", "security": [ { "bearerAuth": [ "templates:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "responses": { "200": { "description": "The template.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateDetail" }, "example": { "object": "template", "id": "3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16", "title": "Mutual NDA", "description": "Two-party non-disclosure agreement.", "roles": [ { "role_name": "Client", "role": "signer", "routing_order": 1 }, { "role_name": "Company", "role": "signer", "routing_order": 2 } ], "field_count": 6, "page_count": 2, "shared_with_team": true, "uses": 41, "created_at": "2026-08-02T11:20:00Z", "updated_at": "2026-10-28T16:45:13Z", "fields": [ { "object": "field", "id": "48213", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null, "role_name": "Client" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/templates/{id}/envelopes": { "post": { "tags": [ "Templates" ], "operationId": "createEnvelopeFromTemplate", "summary": "Create an envelope from a template", "description": "Fills each template role with a person and creates an envelope with the template's document and fields. Sent immediately unless `send` is `false`; if sending fails, the draft is deleted, the quota refunded and you get a 422 with the reason. Role names match case-insensitively, and `roles` may be omitted when every role already has a name and email. Needs both the `templates:write` and `envelopes:write` scopes, and counts against your monthly document allowance.", "security": [ { "bearerAuth": [ "templates:write", "envelopes:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/TemplateId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnvelopeFromTemplateRequest" }, "example": { "roles": [ { "role_name": "Client", "name": "Maya Patel", "email": "maya@example.com" }, { "role_name": "Company", "name": "Rina Koh", "email": "rina@acme.example" } ], "metadata": { "crm_deal_id": "D-10492" }, "expires_in_days": 7 } } } }, "responses": { "201": { "description": "The created envelope.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Mutual NDA", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": "3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16", "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "$ref": "#/components/responses/PaymentRequired" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "description": "Invalid request (`validation_failed`), or the envelope could not be sent: `no_recipients`, `missing_recipient_details`, `unassigned_fields`, `missing_signature_field`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "missing_recipient_details", "message": "Every recipient needs a name and an email address.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEndpoints", "summary": "List webhook endpoints", "description": "Your webhook endpoints (up to 20 per account).", "security": [ { "bearerAuth": [ "webhooks:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of endpoints.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointList" }, "example": { "object": "list", "data": [ { "object": "webhook_endpoint", "id": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54", "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "recipient.completed" ], "enabled": true, "failure_count": 0, "last_success_at": "2026-11-14T09:31:02Z", "last_failure_at": null, "created_at": "2026-11-01T08:00:00Z" } ], "page": 1, "per_page": 20, "total": 1, "has_more": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "tags": [ "Webhooks" ], "operationId": "createWebhookEndpoint", "summary": "Create a webhook endpoint", "description": "Registers an HTTPS URL to receive the events you choose. The response includes the signing `secret` — the only time it is shown. Up to 20 endpoints per account.", "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookRequest" }, "example": { "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "recipient.completed" ] } } } }, "responses": { "201": { "description": "The endpoint, with its secret.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "example": { "object": "webhook_endpoint", "id": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54", "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "recipient.completed" ], "enabled": true, "failure_count": 0, "last_success_at": "2026-11-14T09:31:02Z", "last_failure_at": null, "created_at": "2026-11-01T08:00:00Z", "secret": "whsec_3vY9pQ2mK7tR1xW8cL5nB0dF4hJ6gS2aZ" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "description": "Invalid request (`validation_failed`, e.g. a private or non-HTTPS `url`), or you already have 20 endpoints (`webhook_limit_reached`, `param` `url`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "webhook_limit_reached", "message": "You can have up to 20 webhook endpoints.", "param": "url", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "operationId": "getWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "security": [ { "bearerAuth": [ "webhooks:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "200": { "description": "The endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54", "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "recipient.completed" ], "enabled": true, "failure_count": 0, "last_success_at": "2026-11-14T09:31:02Z", "last_failure_at": null, "created_at": "2026-11-01T08:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "patch": { "tags": [ "Webhooks" ], "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Change the URL, description or events, or switch the endpoint on or off.", "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookRequest" }, "example": { "events": [ "envelope.completed", "envelope.declined", "envelope.voided" ], "enabled": true } } } }, "responses": { "200": { "description": "The updated endpoint.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "example": { "object": "webhook_endpoint", "id": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54", "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "envelope.voided" ], "enabled": true, "failure_count": 0, "last_success_at": "2026-11-14T09:31:02Z", "last_failure_at": null, "created_at": "2026-11-01T08:00:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/ValidationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "tags": [ "Webhooks" ], "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Stops all deliveries to the endpoint and deletes it with its delivery history.", "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" } ], "responses": { "204": { "description": "Deleted.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "tags": [ "Webhooks" ], "operationId": "rotateWebhookSecret", "summary": "Rotate the signing secret", "description": "Replaces the signing secret. The new secret is returned once; deliveries are signed with it from now on, so update your receiver straight away.", "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The endpoint, with its new secret.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "example": { "object": "webhook_endpoint", "id": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54", "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "recipient.completed" ], "enabled": true, "failure_count": 0, "last_success_at": "2026-11-14T09:31:02Z", "last_failure_at": null, "created_at": "2026-11-01T08:00:00Z", "secret": "whsec_3vY9pQ2mK7tR1xW8cL5nB0dF4hJ6gS2aZ" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/webhooks/{id}/test": { "post": { "tags": [ "Webhooks" ], "operationId": "testWebhookEndpoint", "summary": "Send a test event", "description": "Sends a signed `ping` event to the endpoint right away (no retries) and returns the delivery, so you can check your receiver and signature verification. Limited to 10 calls a minute.", "security": [ { "bearerAuth": [ "webhooks:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The ping delivery.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "example": { "object": "webhook_delivery", "id": "a2c5e8f1-6b3d-4d9a-8c7e-1f4b0a9d3e62", "event": "ping", "status": "delivered", "attempts": 1, "response_status": 200, "response_excerpt": "ok", "delivered_at": "2026-11-14T10:05:00Z", "next_retry_at": null, "created_at": "2026-11-14T10:05:00Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "description": "More than 10 tests a minute (`rate_limited`), or your key's rate limit.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Slow down and retry after the Retry-After header.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/webhooks/{id}/deliveries": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookDeliveries", "summary": "List deliveries", "description": "Recent delivery attempts to the endpoint, newest first.", "security": [ { "bearerAuth": [ "webhooks:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/WebhookId" }, { "$ref": "#/components/parameters/Page" }, { "$ref": "#/components/parameters/PerPage" } ], "responses": { "200": { "description": "A page of deliveries.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryList" }, "example": { "object": "list", "data": [ { "object": "webhook_delivery", "id": "a2c5e8f1-6b3d-4d9a-8c7e-1f4b0a9d3e62", "event": "envelope.completed", "status": "delivered", "attempts": 1, "response_status": 200, "response_excerpt": "ok", "delivered_at": "2026-11-15T14:02:43Z", "next_retry_at": null, "created_at": "2026-11-15T14:02:42Z" } ], "page": 1, "per_page": 20, "total": 1, "has_more": false } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/v1/webhook-events": { "get": { "tags": [ "Webhooks" ], "operationId": "listWebhookEvents", "summary": "List event types", "description": "Every event a webhook endpoint can subscribe to (the `ping` test event is not listed).", "security": [ { "bearerAuth": [ "webhooks:read" ] } ], "responses": { "200": { "description": "The event catalogue.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Signkoi-Version": { "$ref": "#/components/headers/Signkoi-Version" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventList" }, "example": { "object": "list", "data": [ { "object": "webhook_event", "name": "envelope.sent", "description": "The envelope was sent and the first recipients were invited." }, { "object": "webhook_event", "name": "envelope.completed", "description": "Every recipient finished; the signed PDF and certificate are ready to download." }, { "object": "webhook_event", "name": "envelope.declined", "description": "A recipient declined to sign, which closes the envelope." }, { "object": "webhook_event", "name": "envelope.voided", "description": "The sender voided the envelope." }, { "object": "webhook_event", "name": "recipient.sent", "description": "A recipient was invited (it is their turn in the routing order)." }, { "object": "webhook_event", "name": "recipient.viewed", "description": "A recipient opened the envelope." }, { "object": "webhook_event", "name": "recipient.completed", "description": "A recipient signed, approved or viewed as required." }, { "object": "webhook_event", "name": "recipient.declined", "description": "A recipient declined to sign." }, { "object": "webhook_event", "name": "recipient.delegated", "description": "A recipient handed their part to someone else (see data.delegated_to)." } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "webhooks": { "envelope.sent": { "post": { "summary": "envelope.sent", "description": "The envelope was sent and the first recipients were invited.", "operationId": "webhook_envelope_sent", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.sent" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "envelope.completed": { "post": { "summary": "envelope.completed", "description": "Every recipient finished; the signed PDF and certificate are ready to download.", "operationId": "webhook_envelope_completed", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.completed" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "envelope.declined": { "post": { "summary": "envelope.declined", "description": "A recipient declined to sign, which closes the envelope.", "operationId": "webhook_envelope_declined", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.declined" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "envelope.voided": { "post": { "summary": "envelope.voided", "description": "The sender voided the envelope.", "operationId": "webhook_envelope_voided", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "envelope.voided" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "recipient.sent": { "post": { "summary": "recipient.sent", "description": "A recipient was invited (it is their turn in the routing order).", "operationId": "webhook_recipient_sent", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.sent" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "recipient.viewed": { "post": { "summary": "recipient.viewed", "description": "A recipient opened the envelope.", "operationId": "webhook_recipient_viewed", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.viewed" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "recipient.completed": { "post": { "summary": "recipient.completed", "description": "A recipient signed, approved or viewed as required.", "operationId": "webhook_recipient_completed", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.completed" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "recipient.declined": { "post": { "summary": "recipient.declined", "description": "A recipient declined to sign.", "operationId": "webhook_recipient_declined", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.declined" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } }, "recipient.delegated": { "post": { "summary": "recipient.delegated", "description": "A recipient handed their part to someone else (see data.delegated_to).", "operationId": "webhook_recipient_delegated", "parameters": [ { "name": "Signkoi-Signature", "in": "header", "required": true, "description": "`t={unix timestamp},v1={hex HMAC-SHA256 of \"{t}.{raw body}\" with the endpoint secret}`", "schema": { "type": "string" } }, { "name": "Signkoi-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "recipient.delegated" } }, { "name": "Signkoi-Delivery", "in": "header", "required": true, "description": "Delivery id; the same across retries.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookPayload" } } } }, "responses": { "200": { "description": "Return any 2xx within 10 seconds to acknowledge." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your API key from https://signkoi.com/app/developer, as `Authorization: Bearer <key>`. Each key carries scopes: envelopes:read, envelopes:write, templates:read, templates:write, webhooks:read, webhooks:write, account:read." } }, "schemas": { "EnvelopeStatus": { "type": "string", "enum": [ "draft", "sent", "completed", "declined", "voided", "expired" ], "description": "`draft` (not sent yet) → `sent` (out for signature) → `completed` (everyone finished). An envelope can also end as `declined`, `voided` or `expired`." }, "RecipientStatus": { "type": "string", "enum": [ "pending", "sent", "viewed", "completed", "declined", "delegated" ], "description": "`pending`: not their turn yet (or the envelope is a draft); `sent`: invited; `viewed`: opened the envelope; `completed`: finished; `declined`; `delegated`: handed over to someone else." }, "RecipientRole": { "type": "string", "enum": [ "signer", "in_person_signer", "approver", "viewer", "cc" ], "description": "`signer` signs remotely; `in_person_signer` signs on your device (embedded signing); `approver` approves without signing; `viewer` must open the document; `cc` gets a copy when it completes." }, "Verification": { "type": "string", "enum": [ "none", "access_code", "email_otp", "sms_otp" ] }, "Language": { "type": "string", "enum": [ "en", "es", "fr", "de", "pt", "it", "nl", "pl", "ru", "ja", "zh", "hi" ] }, "FieldType": { "type": "string", "enum": [ "signature", "initials", "name", "email", "company", "title", "date", "text", "number", "checkbox", "radio", "dropdown", "attachment", "formula", "note" ] }, "Metadata": { "type": "object", "description": "Your own key/value pairs (string → string). Up to 20 keys; keys up to 40 characters of letters, digits, `_`, `.` and `-`; string values up to 500 characters (numbers are converted to strings; booleans and nested objects are rejected). Echoed on the envelope and in webhooks; filter lists with `metadata[key]=value`.", "maxProperties": 20, "propertyNames": { "maxLength": 40, "pattern": "^[A-Za-z0-9_.\\-]+$" }, "additionalProperties": { "type": "string", "maxLength": 500 }, "example": { "crm_deal_id": "D-10492" } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message" ], "properties": { "type": { "type": "string", "enum": [ "invalid_request_error", "authentication_error", "permission_error", "rate_limit_error", "billing_error", "conflict_error", "api_error" ], "description": "Broad error family." }, "code": { "type": "string", "description": "Stable, machine-readable reason. Branch on this." }, "message": { "type": "string", "description": "Human-readable explanation. May change; do not parse it." }, "param": { "type": "string", "description": "The request parameter the error relates to, when there is one." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Validation errors keyed by parameter (only on `validation_failed`)." }, "required_scope": { "type": "string", "description": "The missing scope (only on `insufficient_scope`)." }, "request_id": { "type": "string", "description": "Also in the `X-Request-Id` header. Quote it when contacting support." } } } }, "example": { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such envelope.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } }, "Account": { "type": "object", "required": [ "object", "id", "name", "email", "api_key" ], "properties": { "object": { "type": "string", "const": "account" }, "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "locale": { "type": [ "string", "null" ], "description": "Account language." }, "timezone": { "type": [ "string", "null" ], "description": "IANA time zone." }, "api_key": { "type": "object", "description": "The key that made this request.", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the key stops working; `null` = never." } } }, "plan": { "type": "string", "description": "Only with the `account:read` scope. `free`, `pro`, `business`, …" }, "usage": { "type": "object", "description": "Only with the `account:read` scope.", "properties": { "documents_this_period": { "type": "integer", "description": "Documents created this billing month (website and API)." }, "document_limit": { "type": [ "integer", "null" ], "description": "Monthly allowance; `null` = unlimited." } } } }, "example": { "object": "account", "id": "1842", "name": "Rina Koh", "email": "rina@acme.example", "locale": "en", "timezone": "Europe/London", "api_key": { "id": "311", "name": "CRM integration", "scopes": [ "envelopes:read", "envelopes:write", "account:read" ], "expires_at": null }, "plan": "pro", "usage": { "documents_this_period": 37, "document_limit": 200 } } }, "Recipient": { "type": "object", "required": [ "object", "id", "role", "routing_order", "status" ], "properties": { "object": { "type": "string", "const": "recipient" }, "id": { "type": "string", "format": "uuid" }, "role": { "$ref": "#/components/schemas/RecipientRole" }, "role_name": { "type": [ "string", "null" ], "description": "Template role this recipient fills, if any." }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ], "format": "email" }, "routing_order": { "type": "integer" }, "status": { "$ref": "#/components/schemas/RecipientStatus" }, "language": { "type": [ "string", "null" ] }, "verification": { "$ref": "#/components/schemas/Verification" }, "phone": { "type": [ "string", "null" ], "description": "Masked, e.g. `+44 ••• ••• 4821`." }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "viewed_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "decline_reason": { "type": [ "string", "null" ] } }, "example": { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } }, "Field": { "type": "object", "required": [ "object", "id", "type", "page", "x", "y", "width", "height", "required" ], "properties": { "object": { "type": "string", "const": "field" }, "id": { "type": "string", "description": "Field id." }, "recipient_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The recipient who fills this field." }, "type": { "$ref": "#/components/schemas/FieldType" }, "page": { "type": "integer", "minimum": 1, "description": "Page number, 1-based." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Left edge as a fraction of the page width (origin top-left)." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Top edge as a fraction of the page height (origin top-left)." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Width as a fraction of the page width." }, "height": { "type": "number", "minimum": 0.01, "maximum": 1, "description": "Height as a fraction of the page height." }, "required": { "type": "boolean", "description": "Whether the recipient must fill the field." }, "label": { "type": [ "string", "null" ], "maxLength": 120, "description": "Label shown to the recipient." }, "placeholder": { "type": [ "string", "null" ], "maxLength": 120 }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 120 }, "maxItems": 50, "description": "Choices for `dropdown` (and the value of each `radio` button)." }, "group_name": { "type": [ "string", "null" ], "maxLength": 120, "description": "Groups `radio` buttons; required for radio fields." }, "default_value": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Pre-filled value. Required for `note` fields (the text shown)." }, "validation": { "type": [ "string", "null" ], "enum": [ "email", "number", "phone", "zip", "date", null ], "description": "Input format check for `text` fields." }, "formula": { "type": [ "string", "null" ], "maxLength": 500, "description": "Only for `formula` fields, e.g. `[qty] * [price]`." }, "read_only": { "type": "boolean" }, "font_size": { "type": [ "integer", "null" ], "minimum": 8, "maximum": 20 }, "value": { "description": "Only present once the envelope is `completed`. Text value; `true`/`false` for checkboxes; `{ \"filled\": true }` for signature, initials and attachment fields; `null` if left empty.", "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "object", "properties": { "filled": { "type": "boolean" } } }, { "type": "null" } ] } }, "example": { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } }, "Envelope": { "type": "object", "required": [ "object", "id", "title", "status", "recipients", "files", "created_at" ], "properties": { "object": { "type": "string", "const": "envelope" }, "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "message": { "type": "object", "description": "Email sent to recipients.", "properties": { "subject": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "template_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Template the envelope was created from." }, "source": { "type": "string", "enum": [ "api", "app" ], "description": "Created through the API or on the website." }, "page_count": { "type": "integer" }, "reminders": { "type": "object", "properties": { "delay_days": { "type": [ "integer", "null" ], "description": "Days before the first reminder." }, "frequency_days": { "type": [ "integer", "null" ], "description": "Days between reminders after that." } } }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" }, "description": "Sorted by routing order." }, "files": { "type": "object", "description": "Download URLs (authenticate with your API key). `signed` and `certificate` are `null` until the envelope is completed.", "properties": { "original": { "type": "string", "format": "uri" }, "signed": { "type": [ "string", "null" ], "format": "uri" }, "certificate": { "type": [ "string", "null" ], "format": "uri" } } }, "created_at": { "type": "string", "format": "date-time" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "declined_at": { "type": [ "string", "null" ], "format": "date-time" }, "voided_at": { "type": [ "string", "null" ], "format": "date-time" }, "void_reason": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "After this the envelope can no longer be signed; `null` = never." } }, "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z" } }, "EnvelopeDetail": { "description": "An envelope including its fields (returned by retrieve, create and every update).", "allOf": [ { "$ref": "#/components/schemas/Envelope" }, { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/Field" } } } } ], "example": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "sent", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "pending", "language": "de", "verification": "none", "phone": null, "sent_at": null, "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z", "fields": [ { "object": "field", "id": "48213", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null }, { "object": "field", "id": "48214", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "type": "date", "page": 1, "x": 0.6, "y": 0.84, "width": 0.2, "height": 0.04, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null } ] } }, "AuditEvent": { "type": "object", "properties": { "object": { "type": "string", "const": "audit_event" }, "event": { "type": "string", "description": "e.g. `envelope.sent`, `recipient.viewed`, `recipient.completed`, `envelope.completed`." }, "actor": { "type": [ "object", "null" ], "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] } } }, "recipient_id": { "type": [ "string", "null" ], "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } }, "example": { "object": "audit_event", "event": "recipient.viewed", "actor": { "name": "Maya Patel", "email": "maya@example.com" }, "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "created_at": "2026-11-15T13:58:01Z" } }, "SigningUrl": { "type": "object", "properties": { "object": { "type": "string", "const": "signing_url" }, "url": { "type": "string", "format": "uri", "description": "Opens the signing page for this recipient. Treat it like a password: do not log or share it." }, "recipient_id": { "type": "string", "format": "uuid" } }, "example": { "object": "signing_url", "url": "https://signkoi.com/s/8kQ2…", "recipient_id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73" } }, "TemplateRole": { "type": "object", "properties": { "role_name": { "type": "string", "description": "Name you pass in `roles[].role_name` when using the template." }, "role": { "$ref": "#/components/schemas/RecipientRole" }, "routing_order": { "type": "integer" } } }, "Template": { "type": "object", "properties": { "object": { "type": "string", "const": "template" }, "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateRole" } }, "field_count": { "type": "integer" }, "page_count": { "type": "integer" }, "shared_with_team": { "type": "boolean" }, "uses": { "type": "integer", "description": "How many envelopes were created from it." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "example": { "object": "template", "id": "3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16", "title": "Mutual NDA", "description": "Two-party non-disclosure agreement.", "roles": [ { "role_name": "Client", "role": "signer", "routing_order": 1 }, { "role_name": "Company", "role": "signer", "routing_order": 2 } ], "field_count": 6, "page_count": 2, "shared_with_team": true, "uses": 41, "created_at": "2026-08-02T11:20:00Z", "updated_at": "2026-10-28T16:45:13Z" } }, "TemplateField": { "type": "object", "required": [ "object", "id", "type", "page", "x", "y", "width", "height", "required" ], "properties": { "object": { "type": "string", "const": "field" }, "id": { "type": "string", "description": "Field id." }, "role_name": { "type": "string", "description": "The template role that fills this field." }, "type": { "$ref": "#/components/schemas/FieldType" }, "page": { "type": "integer", "minimum": 1, "description": "Page number, 1-based." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Left edge as a fraction of the page width (origin top-left)." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Top edge as a fraction of the page height (origin top-left)." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Width as a fraction of the page width." }, "height": { "type": "number", "minimum": 0.01, "maximum": 1, "description": "Height as a fraction of the page height." }, "required": { "type": "boolean", "description": "Whether the recipient must fill the field." }, "label": { "type": [ "string", "null" ], "maxLength": 120, "description": "Label shown to the recipient." }, "placeholder": { "type": [ "string", "null" ], "maxLength": 120 }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 120 }, "maxItems": 50, "description": "Choices for `dropdown` (and the value of each `radio` button)." }, "group_name": { "type": [ "string", "null" ], "maxLength": 120, "description": "Groups `radio` buttons; required for radio fields." }, "default_value": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Pre-filled value. Required for `note` fields (the text shown)." }, "validation": { "type": [ "string", "null" ], "enum": [ "email", "number", "phone", "zip", "date", null ], "description": "Input format check for `text` fields." }, "formula": { "type": [ "string", "null" ], "maxLength": 500, "description": "Only for `formula` fields, e.g. `[qty] * [price]`." }, "read_only": { "type": "boolean" }, "font_size": { "type": [ "integer", "null" ], "minimum": 8, "maximum": 20 } }, "example": { "object": "field", "id": "48213", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null, "role_name": "Client" } }, "TemplateDetail": { "allOf": [ { "$ref": "#/components/schemas/Template" }, { "type": "object", "properties": { "fields": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateField" } } } } ], "example": { "object": "template", "id": "3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16", "title": "Mutual NDA", "description": "Two-party non-disclosure agreement.", "roles": [ { "role_name": "Client", "role": "signer", "routing_order": 1 }, { "role_name": "Company", "role": "signer", "routing_order": 2 } ], "field_count": 6, "page_count": 2, "shared_with_team": true, "uses": 41, "created_at": "2026-08-02T11:20:00Z", "updated_at": "2026-10-28T16:45:13Z", "fields": [ { "object": "field", "id": "48213", "type": "signature", "page": 1, "x": 0.12, "y": 0.82, "width": 0.3, "height": 0.06, "required": true, "label": null, "placeholder": null, "options": null, "group_name": null, "default_value": null, "validation": null, "formula": null, "read_only": false, "font_size": null, "role_name": "Client" } ] } }, "WebhookEndpoint": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_endpoint" }, "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "description": { "type": [ "string", "null" ] }, "events": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean", "description": "Switched off automatically after 20 consecutive failed deliveries." }, "failure_count": { "type": "integer", "description": "Consecutive failed attempts; reset by a success." }, "last_success_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_failure_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "example": { "object": "webhook_endpoint", "id": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54", "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "recipient.completed" ], "enabled": true, "failure_count": 0, "last_success_at": "2026-11-14T09:31:02Z", "last_failure_at": null, "created_at": "2026-11-01T08:00:00Z" } }, "WebhookEndpointWithSecret": { "description": "Returned only on create and rotate-secret: the only time you see the signing secret.", "allOf": [ { "$ref": "#/components/schemas/WebhookEndpoint" }, { "type": "object", "properties": { "secret": { "type": "string", "description": "Signing secret (`whsec_…`). Store it securely; it is not shown again." } } } ], "example": { "object": "webhook_endpoint", "id": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54", "url": "https://example.com/webhooks/signkoi", "description": "Production CRM sync", "events": [ "envelope.completed", "envelope.declined", "recipient.completed" ], "enabled": true, "failure_count": 0, "last_success_at": "2026-11-14T09:31:02Z", "last_failure_at": null, "created_at": "2026-11-01T08:00:00Z", "secret": "whsec_3vY9pQ2mK7tR1xW8cL5nB0dF4hJ6gS2aZ" } }, "WebhookDelivery": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_delivery" }, "id": { "type": "string", "format": "uuid" }, "event": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "delivered", "retrying", "failed" ], "description": "`pending`: not attempted yet; `delivered`: your endpoint returned 2xx; `retrying`: the last attempt failed and another is scheduled (`next_retry_at`); `failed`: every retry failed." }, "attempts": { "type": "integer" }, "response_status": { "type": [ "integer", "null" ], "description": "HTTP status your endpoint returned on the last attempt." }, "response_excerpt": { "type": [ "string", "null" ], "maxLength": 1000, "description": "First 1,000 characters of your response body, or why the request could not be sent." }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "next_retry_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "example": { "object": "webhook_delivery", "id": "a2c5e8f1-6b3d-4d9a-8c7e-1f4b0a9d3e62", "event": "envelope.completed", "status": "delivered", "attempts": 1, "response_status": 200, "response_excerpt": "ok", "delivered_at": "2026-11-15T14:02:43Z", "next_retry_at": null, "created_at": "2026-11-15T14:02:42Z" } }, "WebhookEvent": { "type": "object", "properties": { "object": { "type": "string", "const": "webhook_event" }, "name": { "type": "string" }, "description": { "type": "string" } }, "example": { "object": "webhook_event", "name": "envelope.completed", "description": "Every recipient finished; the signed PDF and certificate are ready to download." } }, "WebhookPayload": { "type": "object", "description": "Body of every webhook delivery.", "properties": { "id": { "type": "string", "description": "Event id (`evt_…`). Use it to ignore duplicates." }, "event": { "type": "string" }, "api_version": { "type": "string", "description": "Version of the `data.envelope` shape, e.g. `2026-11-14`." }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "envelope": { "$ref": "#/components/schemas/Envelope", "description": "The envelope as the API returns it (without fields)." }, "document": { "type": "object", "description": "Compact legacy summary. `status` uses internal names (`awaiting_signature`, `signed`, …); prefer `data.envelope.status`.", "properties": { "id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "status": { "type": "string" }, "metadata": { "$ref": "#/components/schemas/Metadata" } } }, "recipient": { "type": "object", "description": "Only on `recipient.*` events. `status` uses internal names; match on `id` against `data.envelope.recipients`.", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "role": { "type": "string" }, "status": { "type": "string" } } }, "delegated_to": { "type": "object", "description": "Only on `recipient.delegated`: the new recipient." } } } }, "example": { "id": "evt_01jcz8q6x4m7r2t9v3w5y8b1d4", "event": "recipient.completed", "api_version": "2026-11-14", "created_at": "2026-11-15T14:02:40+00:00", "data": { "document": { "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "awaiting_signature", "metadata": { "crm_deal_id": "D-10492" } }, "recipient": { "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "name": "Maya Patel", "email": "maya@example.com", "role": "signer", "status": "completed" }, "envelope": { "object": "envelope", "id": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47", "title": "Consulting agreement — Acme Ltd", "status": "sent", "message": { "subject": "Please sign: Consulting agreement", "body": "Hi Maya, here is the agreement we discussed." }, "metadata": { "crm_deal_id": "D-10492" }, "template_id": null, "source": "api", "page_count": 3, "reminders": { "delay_days": 2, "frequency_days": 3 }, "recipients": [ { "object": "recipient", "id": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73", "role": "signer", "role_name": null, "name": "Maya Patel", "email": "maya@example.com", "routing_order": 1, "status": "completed", "language": "en", "verification": "email_otp", "phone": null, "sent_at": "2026-11-14T09:30:12Z", "viewed_at": "2026-11-15T13:58:01Z", "completed_at": "2026-11-15T14:02:40Z", "declined_at": null, "decline_reason": null }, { "object": "recipient", "id": "e7b3d915-0c4a-4b6e-8f27-5a1c9d3e6b08", "role": "cc", "role_name": null, "name": "Jonas Weber", "email": "jonas@example.com", "routing_order": 2, "status": "sent", "language": "de", "verification": "none", "phone": null, "sent_at": "2026-11-15T14:02:41Z", "viewed_at": null, "completed_at": null, "declined_at": null, "decline_reason": null } ], "files": { "original": "https://signkoi.com/api/v1/envelopes/9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47/files/original", "signed": null, "certificate": null }, "created_at": "2026-11-14T09:30:05Z", "sent_at": "2026-11-14T09:30:12Z", "completed_at": null, "declined_at": null, "voided_at": null, "void_reason": null, "expires_at": "2026-12-14T09:30:12Z" } } } }, "EnvelopeList": { "type": "object", "description": "A page of envelopes (without fields).", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Envelope" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean", "description": "Whether another page follows." } } }, "TemplateList": { "type": "object", "description": "A page of templates.", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Template" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean", "description": "Whether another page follows." } } }, "WebhookEndpointList": { "type": "object", "description": "A page of webhook endpoints.", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean", "description": "Whether another page follows." } } }, "WebhookDeliveryList": { "type": "object", "description": "Recent deliveries, newest first.", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean", "description": "Whether another page follows." } } }, "WebhookEventList": { "type": "object", "description": "Every event you can subscribe to.", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "AuditEventList": { "type": "object", "description": "The audit trail, oldest first.", "properties": { "object": { "type": "string", "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean", "description": "Whether another page follows." } } }, "RecipientInput": { "type": "object", "required": [ "name", "email" ], "properties": { "key": { "type": "string", "maxLength": 64, "description": "Your own reference for this recipient (unique within the request), so fields can point at it with `recipient_key`." }, "name": { "type": "string", "maxLength": 255, "description": "Recipient name." }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "role": { "$ref": "#/components/schemas/RecipientRole", "description": "Defaults to `signer`." }, "routing_order": { "type": "integer", "minimum": 1, "default": 1, "description": "Recipients with the same number are invited together; higher numbers wait." }, "language": { "$ref": "#/components/schemas/Language", "description": "Language of the emails and signing page. Defaults to your account language." }, "verification": { "$ref": "#/components/schemas/Verification", "description": "Extra identity check before signing. Defaults to `none`." }, "access_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Required when `verification` is `access_code`. Share it with the recipient yourself; it is stored hashed and never returned." }, "phone": { "type": [ "string", "null" ], "description": "E.164 phone number, required when `verification` is `sms_otp`. Returned masked." }, "private_message": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Note only this recipient sees." } } }, "FieldInput": { "type": "object", "required": [ "type", "page", "x", "y", "width", "height" ], "properties": { "recipient_key": { "type": "string", "description": "The `key` of the recipient who fills the field (wins over `recipient_index`)…" }, "recipient_index": { "type": "integer", "minimum": 0, "description": "…or their 0-based position in `recipients`." }, "type": { "$ref": "#/components/schemas/FieldType" }, "page": { "type": "integer", "minimum": 1, "description": "Page number, 1-based." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Left edge as a fraction of the page width (origin top-left)." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Top edge as a fraction of the page height (origin top-left)." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Width as a fraction of the page width." }, "height": { "type": "number", "minimum": 0.01, "maximum": 1, "description": "Height as a fraction of the page height." }, "required": { "type": "boolean", "description": "Whether the recipient must fill the field." }, "label": { "type": [ "string", "null" ], "maxLength": 120, "description": "Label shown to the recipient." }, "placeholder": { "type": [ "string", "null" ], "maxLength": 120 }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 120 }, "maxItems": 50, "description": "Choices for `dropdown` (and the value of each `radio` button)." }, "group_name": { "type": [ "string", "null" ], "maxLength": 120, "description": "Groups `radio` buttons; required for radio fields." }, "default_value": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Pre-filled value. Required for `note` fields (the text shown)." }, "validation": { "type": [ "string", "null" ], "enum": [ "email", "number", "phone", "zip", "date", null ], "description": "Input format check for `text` fields." }, "formula": { "type": [ "string", "null" ], "maxLength": 500, "description": "Only for `formula` fields, e.g. `[qty] * [price]`." }, "read_only": { "type": "boolean" }, "font_size": { "type": [ "integer", "null" ], "minimum": 8, "maximum": 20 } }, "description": "Reference the recipient with `recipient_key` or `recipient_index`. Signature, initials, date and input fields need a `signer` or `in_person_signer`." }, "MessageInput": { "type": "object", "properties": { "subject": { "type": [ "string", "null" ], "maxLength": 200, "description": "Defaults to \"Please sign: {title}\"." }, "body": { "type": [ "string", "null" ], "maxLength": 2000 } } }, "RemindersInput": { "type": "object", "properties": { "delay_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 60 }, "frequency_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 60 } } }, "CreateEnvelopeRequest": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "minItems": 1, "maxItems": 10, "description": "PDFs, base64-encoded (up to 10; the same size limits as uploads on the website, 25 MB by default). Several files are merged into one envelope in order.", "items": { "type": "object", "required": [ "content_base64" ], "properties": { "name": { "type": "string", "description": "File name, e.g. `agreement.pdf`. Defaults to `document-N.pdf`." }, "content_base64": { "type": "string", "contentEncoding": "base64", "description": "Base64 PDF. A `data:application/pdf;base64,` prefix and line breaks are accepted." } } } }, "title": { "type": "string", "description": "Defaults to the first file name without its extension." }, "message": { "$ref": "#/components/schemas/MessageInput" }, "recipients": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientInput" } }, "fields": { "type": "array", "items": { "$ref": "#/components/schemas/FieldInput" }, "description": "If omitted, a signature box is placed on the last page for the first signer." }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "expires_in_days": { "type": [ "integer", "null" ], "enum": [ 1, 3, 7, 30, null ], "description": "Days the envelope stays signable after sending; `null` = never expires." }, "reminders": { "$ref": "#/components/schemas/RemindersInput" }, "send": { "type": "boolean", "default": false, "description": "Send immediately. If sending fails validation nothing is kept and you get a 422 with the reason." } } }, "CreateEnvelopeMultipart": { "type": "object", "description": "Same as the JSON body, but upload the PDF(s) as files. `recipients`, `fields`, `metadata`, `message` and `reminders` are JSON-encoded strings.", "properties": { "file": { "type": "string", "format": "binary", "description": "One PDF…" }, "files[]": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "…or several (up to 10)." }, "title": { "type": "string" }, "recipients": { "type": "string", "description": "JSON array of RecipientInput." }, "fields": { "type": "string", "description": "JSON array of FieldInput." }, "metadata": { "type": "string", "description": "JSON object." }, "message": { "type": "string", "description": "JSON object `{subject, body}`." }, "reminders": { "type": "string", "description": "JSON object `{delay_days, frequency_days}`." }, "expires_in_days": { "type": "integer" }, "send": { "type": "boolean" } } }, "UpdateEnvelopeRequest": { "type": "object", "description": "`title`, `message`, `expires_in_days` and `reminders` can only change while the envelope is a draft (409 `envelope_not_draft` otherwise). `metadata` can change at any time.", "properties": { "title": { "type": "string" }, "message": { "type": [ "object", "null" ], "properties": { "subject": { "type": [ "string", "null" ], "maxLength": 200, "description": "Defaults to \"Please sign: {title}\"." }, "body": { "type": [ "string", "null" ], "maxLength": 2000 } }, "description": "`null` clears both subject and body." }, "expires_in_days": { "type": [ "integer", "null" ], "enum": [ 1, 3, 7, 30, null ], "description": "Days the envelope stays signable after sending; `null` = no expiry." }, "reminders": { "$ref": "#/components/schemas/RemindersInput" }, "metadata": { "type": [ "object", "null" ], "description": "Merged into the existing metadata. Set a key to `null` to delete it, or pass `metadata: null` to clear all keys.", "additionalProperties": { "type": [ "string", "null" ], "maxLength": 500 } } } }, "ReplaceRecipientsRequest": { "type": "object", "required": [ "recipients" ], "properties": { "recipients": { "type": "array", "description": "The complete new set, as full objects. Pass `id` to keep an existing recipient (and their fields); recipients you leave out are removed with their fields. For a kept recipient, omitting `access_code` or `phone` keeps the stored value. An unknown `id` is a 422 (`param` `recipients.N.id`).", "items": { "type": "object", "required": [ "name", "email" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Existing recipient to keep." }, "name": { "type": "string", "maxLength": 255, "description": "Recipient name." }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "role": { "$ref": "#/components/schemas/RecipientRole", "description": "Defaults to `signer`." }, "routing_order": { "type": "integer", "minimum": 1, "default": 1, "description": "Recipients with the same number are invited together; higher numbers wait." }, "language": { "$ref": "#/components/schemas/Language", "description": "Language of the emails and signing page. Defaults to your account language." }, "verification": { "$ref": "#/components/schemas/Verification", "description": "Extra identity check before signing. Defaults to `none`." }, "access_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Required when `verification` is `access_code`. Share it with the recipient yourself; it is stored hashed and never returned." }, "phone": { "type": [ "string", "null" ], "description": "E.164 phone number, required when `verification` is `sms_otp`. Returned masked." }, "private_message": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Note only this recipient sees." } } } } } }, "ReplaceFieldsRequest": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "description": "The complete new set of fields; existing fields are replaced.", "items": { "type": "object", "required": [ "recipient_id", "type", "page", "x", "y", "width", "height" ], "properties": { "recipient_id": { "type": "string", "format": "uuid", "description": "The recipient who fills the field." }, "type": { "$ref": "#/components/schemas/FieldType" }, "page": { "type": "integer", "minimum": 1, "description": "Page number, 1-based." }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "Left edge as a fraction of the page width (origin top-left)." }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "Top edge as a fraction of the page height (origin top-left)." }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "Width as a fraction of the page width." }, "height": { "type": "number", "minimum": 0.01, "maximum": 1, "description": "Height as a fraction of the page height." }, "required": { "type": "boolean", "description": "Whether the recipient must fill the field." }, "label": { "type": [ "string", "null" ], "maxLength": 120, "description": "Label shown to the recipient." }, "placeholder": { "type": [ "string", "null" ], "maxLength": 120 }, "options": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 120 }, "maxItems": 50, "description": "Choices for `dropdown` (and the value of each `radio` button)." }, "group_name": { "type": [ "string", "null" ], "maxLength": 120, "description": "Groups `radio` buttons; required for radio fields." }, "default_value": { "type": [ "string", "null" ], "maxLength": 2000, "description": "Pre-filled value. Required for `note` fields (the text shown)." }, "validation": { "type": [ "string", "null" ], "enum": [ "email", "number", "phone", "zip", "date", null ], "description": "Input format check for `text` fields." }, "formula": { "type": [ "string", "null" ], "maxLength": 500, "description": "Only for `formula` fields, e.g. `[qty] * [price]`." }, "read_only": { "type": "boolean" }, "font_size": { "type": [ "integer", "null" ], "minimum": 8, "maximum": 20 } } } } } }, "VoidEnvelopeRequest": { "type": "object", "required": [ "reason" ], "properties": { "reason": { "type": "string", "maxLength": 500, "description": "Shown to the recipients in the void email." } } }, "UpdateRecipientRequest": { "type": "object", "description": "Correct a recipient who has not finished yet. Changing the email issues a new signing link (the old one stops working) and re-sends the invitation if it is their turn.", "properties": { "name": { "type": "string", "maxLength": 255, "description": "Recipient name." }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "language": { "$ref": "#/components/schemas/Language", "description": "Language of the emails and signing page. Defaults to your account language." }, "verification": { "$ref": "#/components/schemas/Verification", "description": "Extra identity check before signing. Defaults to `none`." }, "access_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Required when `verification` is `access_code`. Share it with the recipient yourself; it is stored hashed and never returned." }, "phone": { "type": [ "string", "null" ], "description": "E.164 phone number, required when `verification` is `sms_otp`. Returned masked." }, "private_message": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Note only this recipient sees." } } }, "CreateEnvelopeFromTemplateRequest": { "type": "object", "properties": { "title": { "type": "string", "minLength": 2, "maxLength": 150, "description": "Defaults to the template title." }, "message": { "$ref": "#/components/schemas/TemplateMessageInput" }, "roles": { "type": "array", "description": "Who fills each template role. `role_name` matching is case-insensitive. May be omitted when every role of the template already has a name and email.", "items": { "type": "object", "required": [ "role_name", "name", "email" ], "properties": { "role_name": { "type": "string", "description": "Must match a role of the template (case-insensitive)." }, "name": { "type": "string", "maxLength": 255, "description": "Recipient name." }, "email": { "type": "string", "format": "email", "maxLength": 255 }, "language": { "$ref": "#/components/schemas/Language", "description": "Language of the emails and signing page. Defaults to your account language." }, "verification": { "$ref": "#/components/schemas/Verification", "description": "Extra identity check before signing. Defaults to `none`." }, "access_code": { "type": [ "string", "null" ], "maxLength": 64, "description": "Required when `verification` is `access_code`. Share it with the recipient yourself; it is stored hashed and never returned." }, "phone": { "type": [ "string", "null" ], "description": "E.164 phone number, required when `verification` is `sms_otp`. Returned masked." } } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "expires_in_days": { "type": [ "integer", "null" ], "enum": [ 1, 3, 7, 30, null ], "description": "Days the envelope stays signable after sending; `null` = never expires." }, "send": { "type": "boolean", "default": true, "description": "Send immediately (default). Pass `false` to create a draft. If sending fails, the draft is deleted, the quota refunded and you get a 422 with the reason." } } }, "CreateWebhookRequest": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "Public HTTPS URL. Private, loopback and link-local addresses are refused." }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "envelope.sent", "envelope.completed", "envelope.declined", "envelope.voided", "recipient.sent", "recipient.viewed", "recipient.completed", "recipient.declined", "recipient.delegated" ] } }, "enabled": { "type": "boolean", "default": true } } }, "UpdateWebhookRequest": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 }, "description": { "type": [ "string", "null" ], "maxLength": 255 }, "events": { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "envelope.sent", "envelope.completed", "envelope.declined", "envelope.voided", "recipient.sent", "recipient.viewed", "recipient.completed", "recipient.declined", "recipient.delegated" ] } }, "enabled": { "type": "boolean", "description": "Re-enable an endpoint that was switched off after repeated failures (resets the failure count)." } } }, "TemplateMessageInput": { "type": "object", "properties": { "subject": { "type": [ "string", "null" ], "maxLength": 255, "description": "Defaults to \"Please sign: {title}\"." }, "body": { "type": [ "string", "null" ], "maxLength": 5000 } } } }, "parameters": { "EnvelopeId": { "name": "id", "in": "path", "required": true, "description": "Envelope id.", "schema": { "type": "string", "format": "uuid" }, "example": "9b2f4c1e-7a3d-4e8b-9c51-2d6f8a0b3e47" }, "RecipientId": { "name": "rid", "in": "path", "required": true, "description": "Recipient id.", "schema": { "type": "string", "format": "uuid" }, "example": "c4e1a8f2-3b7d-4f19-a6c2-8e5d0b9f1a73" }, "TemplateId": { "name": "id", "in": "path", "required": true, "description": "Template id.", "schema": { "type": "string", "format": "uuid" }, "example": "3f8a6d2c-1e9b-4c75-b0a4-7d2e5f8c9a16" }, "WebhookId": { "name": "id", "in": "path", "required": true, "description": "Webhook endpoint id.", "schema": { "type": "string", "format": "uuid" }, "example": "6d1e9f3a-4b2c-4a87-9e5d-0f7b3c8a2d54" }, "Page": { "name": "page", "in": "query", "description": "Page number, starting at 1.", "schema": { "type": "integer", "minimum": 1, "default": 1 } }, "PerPage": { "name": "per_page", "in": "query", "description": "Items per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (1–255 chars), e.g. a UUID. Retrying with the same key and body within 24 hours returns the original response instead of repeating the action.", "schema": { "type": "string", "maxLength": 255 }, "example": "5f1d7c1e-0b8a-4c2e-9f3d-61a2b7e4c905" } }, "headers": { "X-Request-Id": { "description": "Unique id of this request. Quote it when contacting support.", "schema": { "type": "string" } }, "Signkoi-Version": { "description": "API version that served the request.", "schema": { "type": "string", "example": "2026-11-14" } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (on 429).", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` when the response is a replay of an earlier request with the same Idempotency-Key.", "schema": { "type": "string" } } }, "responses": { "Unauthorized": { "description": "Missing, invalid, expired or revoked API key (`api_key_missing`, `invalid_api_key`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "The API key is invalid, expired or revoked.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "Forbidden": { "description": "The key lacks a required scope (`insufficient_scope`) or the account is suspended (`account_suspended`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "permission_error", "code": "insufficient_scope", "message": "This API key doesn't have the \"envelopes:write\" scope.", "required_scope": "envelopes:write", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "NotFound": { "description": "No such resource, or it belongs to someone else (`resource_missing`, e.g. \"No such envelope.\" / \"No such recipient.\").", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "resource_missing", "message": "No such envelope.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "Conflict": { "description": "The resource's current state does not allow this action (e.g. `envelope_not_draft`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "conflict_error", "code": "envelope_not_draft", "message": "Only draft envelopes can be changed. Void it instead.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "ValidationFailed": { "description": "Invalid parameters (`validation_failed`, with `param` and `errors`) or a business rule failed (e.g. `missing_signature_field`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "validation_failed", "message": "The recipients.0.email field must be a valid email address.", "param": "recipients.0.email", "errors": { "recipients.0.email": [ "The recipients.0.email field must be a valid email address." ] }, "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "PaymentRequired": { "description": "The plan's monthly document allowance is used up (`plan_limit`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "billing_error", "code": "plan_limit", "message": "You have reached your plan's limit of 3 documents this month.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "PayloadTooLarge": { "description": "A file, or all files together, is larger than allowed (`file_too_large`).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "invalid_request_error", "code": "file_too_large", "message": "The file is larger than 25 MB.", "param": "files.0", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "RateLimited": { "description": "Too many requests (`rate_limited`): your key's per-minute limit, or an endpoint's own limit. Wait for `Retry-After` seconds.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "Too many requests. Slow down and retry after the Retry-After header.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } }, "ServerError": { "description": "Something went wrong on our side (`internal_error`). Safe to retry with the same Idempotency-Key.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "type": "api_error", "code": "internal_error", "message": "Something went wrong on our side. Retry, and contact support with the request_id if it persists.", "request_id": "0f6c8f5e-2b1d-4c3a-9e7f-5a8b1c2d3e4f" } } } } } } } }