{ "openapi": "3.0.3", "info": { "title": "SignFox API", "description": "REST API for SignFox e-signatures: create templates, place fields, send envelopes, track signing, and download signed PDFs. Authenticate with an API key created in Settings \u2192 API keys, passed as a Bearer token. Requests are rate-limited to 120 per minute per key. Mutating POST endpoints that create resources accept an optional `Idempotency-Key` header (max 200 characters): the first successful response for a given key is stored and replayed verbatim on retries with an `Idempotency-Replayed: true` response header; failed requests are not cached and may be retried with the same key.", "version": "1.0.0", "contact": { "email": "hello@signfox.co" } }, "servers": [ { "url": "https://signfox.co/api/v1" } ], "security": [ { "apiKey": [] } ], "tags": [ { "name": "Templates", "description": "Reusable documents with signature fields." }, { "name": "Envelopes", "description": "A template instance sent to recipients for signature." }, { "name": "Documents", "description": "One-call document signing: upload a rendered PDF, field positions, and recipients in a single request." } ], "paths": { "/envelopes": { "get": { "tags": [ "Envelopes" ], "summary": "List envelopes", "operationId": "listEnvelopes", "parameters": [ { "name": "page", "in": "query", "description": "1-based page number (default 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "pageSize", "in": "query", "description": "Items per page (default 50, max 100).", "schema": { "type": "integer", "default": 50, "maximum": 100 } }, { "name": "status", "in": "query", "description": "Filter by envelope status.", "schema": { "$ref": "#/components/schemas/EnvelopeStatus" } }, { "name": "q", "in": "query", "description": "Case-insensitive search over subject, template name, and recipient name/email.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Only envelopes created at or after this ISO 8601 date-time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "Only envelopes created at or before this ISO 8601 date-time.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Paginated envelope list.", "content": { "application/json": { "schema": { "type": "object", "required": [ "envelopes", "pagination" ], "properties": { "envelopes": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "externalRef": { "type": "string", "nullable": true }, "template": { "type": "string", "description": "Template name." }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "email": { "type": "string" }, "status": { "$ref": "#/components/schemas/RecipientStatus" } } } } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Envelopes" ], "summary": "Create (and optionally send) an envelope", "description": "Creates an envelope from an ACTIVE template and, unless `send` is `false`, immediately sends it to recipients. Each recipient's `role` must match a field role on the template. Recipients with `kind: \"SIGNER\"` (the default) sign the document; `kind: \"CC\"` recipients only receive the completed document. Signing proceeds in ascending `order`; recipients sharing the same `order` value form a parallel group and may sign in any sequence relative to each other.\n\nIf `callbackUrl` is provided, `callbackSecret` is required.", "operationId": "createEnvelope", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "templateId", "recipients" ], "properties": { "templateId": { "type": "integer", "description": "Id of an ACTIVE template." }, "recipients": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "name", "email", "role", "order" ], "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "role": { "type": "string", "description": "Must match a template field role, e.g. \"signer1\"." }, "order": { "type": "integer", "description": "Signing order. Equal values form a parallel signing group." }, "kind": { "type": "string", "enum": [ "SIGNER", "CC" ], "default": "SIGNER", "description": "SIGNER signs; CC receives the completed document only." } } } }, "subject": { "type": "string" }, "message": { "type": "string" }, "signerChallenge": { "type": "string", "enum": [ "NONE", "EMAIL_OTP" ], "description": "Identity challenge signers must pass before signing." }, "signatureTier": { "type": "string", "enum": [ "ELECTRONIC", "DIGITAL" ], "description": "ELECTRONIC (image + audit trail) or DIGITAL (PAdES cryptographic signature)." }, "signatureMethod": { "type": "string", "enum": [ "ORG_CERT", "TOKEN", "AADHAAR" ], "description": "For DIGITAL envelopes: who holds the signing key." }, "externalRef": { "type": "string", "description": "Your correlation id, echoed in list responses." }, "callbackUrl": { "type": "string", "description": "Webhook URL for lifecycle events (SENT, SIGNED, COMPLETED, VOIDED). Requires `callbackSecret`." }, "callbackSecret": { "type": "string", "description": "HMAC secret used to sign webhook payloads. Required when `callbackUrl` is set." }, "expiresInDays": { "type": "integer", "description": "Days until the envelope expires." }, "send": { "type": "boolean", "default": true, "description": "Set false to create a DRAFT without emailing recipients." } } } } } }, "responses": { "201": { "description": "Envelope created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "enum": [ "DRAFT", "SENT" ] }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "email": { "type": "string" }, "signingUrlToken": { "type": "string", "description": "Token for the recipient's signing URL: https://signfox.co/sign/{token}" } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "get": { "tags": [ "Envelopes" ], "summary": "Get an envelope", "operationId": "getEnvelope", "responses": { "200": { "description": "Envelope detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "patch": { "tags": [ "Envelopes" ], "summary": "Update an envelope's subject or message", "description": "Allowed only while the envelope is DRAFT or SENT. Envelopes in any other state return 409.", "operationId": "updateEnvelope", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "subject": { "type": "string" }, "message": { "type": "string" } } } } } }, "responses": { "200": { "description": "Updated envelope detail.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnvelopeDetail" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "The envelope is no longer editable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}/void": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "post": { "tags": [ "Envelopes" ], "summary": "Void an envelope", "operationId": "voidEnvelope", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string" } } } } } }, "responses": { "200": { "description": "Envelope voided.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "VOIDED" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/envelopes/{id}/signed-pdf": { "parameters": [ { "$ref": "#/components/parameters/EnvelopeId" } ], "get": { "tags": [ "Envelopes" ], "summary": "Download the signed PDF", "description": "Available once the envelope is COMPLETED and the final PDF has been produced (check `signedPdfAvailable` on the envelope).", "operationId": "getSignedPdf", "responses": { "200": { "description": "The signed PDF, as an attachment.", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Envelope not found or signed PDF not yet available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/documents/envelope": { "post": { "tags": [ "Documents" ], "summary": "Create a signing envelope from an uploaded PDF", "description": "One-call endpoint: upload a rendered PDF, field positions, and recipients and receive a SENT envelope with signing tokens \u2014 without pre-registering a reusable template. Ideal for API consumers (e.g. dpflo) who keep documents on their side and use SignFox only for the signing ceremony.\n\nCreates a transient ADHOC template internally (hidden from GET /templates listings), places the fields, activates it, then creates and sends the envelope using the same path as POST /envelopes. All envelope semantics \u2014 signing tokens, challenge, webhooks, audit \u2014 are identical.\n\nCoordinates (`x`, `y`, `width`, `height`) are fractions of the page in the range [0, 1] with the origin at the top-left. `x + width` and `y + height` must not exceed 1. Pages are 1-based.\n\nIf `callbackUrl` is provided, `callbackSecret` is required.", "operationId": "createDocumentEnvelope", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "title", "recipients", "fields" ], "properties": { "file": { "type": "string", "format": "binary", "description": "The PDF to be signed. Must begin with the `%PDF-` magic bytes." }, "title": { "type": "string", "description": "Document title stored on the envelope." }, "fields": { "type": "string", "description": "JSON array of field definitions (required; at least one entry). Each field: `{ recipientRole, type, page, x, y, width, height, label?, required? }`. Roles must match a SIGNER in `recipients`.", "example": "[{\"recipientRole\":\"signer1\",\"type\":\"SIGNATURE\",\"page\":1,\"x\":0.1,\"y\":0.8,\"width\":0.3,\"height\":0.08}]" }, "recipients": { "type": "string", "description": "JSON array of recipient objects: `[{ order, role, name, email, kind?, phone?, personalMessage? }]`. At least one SIGNER required. Roles for SIGNER recipients must each have at least one field in `fields`. Equal `order` values form a parallel signing group.", "example": "[{\"order\":1,\"role\":\"signer1\",\"name\":\"Alice\",\"email\":\"alice@example.com\"}]" }, "subject": { "type": "string", "description": "Email subject for sign-request emails." }, "message": { "type": "string", "description": "Email body for sign-request emails." }, "signerChallenge": { "type": "string", "enum": [ "NONE", "EMAIL_OTP", "SMS_OTP" ], "description": "Identity challenge signers must pass before signing. Default: NONE." }, "signatureTier": { "type": "string", "enum": [ "ELECTRONIC", "DIGITAL" ], "description": "ELECTRONIC (image + audit trail) or DIGITAL (PAdES cryptographic signature). Default: org setting." }, "signatureMethod": { "type": "string", "enum": [ "ORG_CERT", "TOKEN", "AADHAAR" ], "description": "For DIGITAL envelopes: who holds the signing key." }, "externalRef": { "type": "string", "description": "Your correlation id, stored on the envelope and echoed in webhook payloads." }, "callbackUrl": { "type": "string", "description": "Webhook URL for lifecycle events (SENT, SIGNED, COMPLETED, VOIDED). Requires `callbackSecret`." }, "callbackSecret": { "type": "string", "description": "HMAC secret used to sign webhook payloads. Required when `callbackUrl` is set." }, "expiresInDays": { "type": "string", "description": "Number of days until the envelope expires (integer as a string)." }, "send": { "type": "string", "enum": [ "true", "false" ], "default": "true", "description": "Pass `\"false\"` to create a DRAFT envelope without emailing recipients." } } } } } }, "responses": { "201": { "description": "Envelope created (and sent, unless `send=false`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "Envelope id." }, "status": { "type": "string", "enum": [ "DRAFT", "SENT" ] }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "email": { "type": "string" }, "signingUrlToken": { "type": "string", "description": "Token for the recipient's signing page: `{appBaseUrl}/sign/{token}`." } } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates", "operationId": "listTemplates", "parameters": [ { "name": "page", "in": "query", "description": "1-based page number (default 1).", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "pageSize", "in": "query", "description": "Items per page (default 50, max 100).", "schema": { "type": "integer", "default": 50, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated template list (includes archived templates).", "content": { "application/json": { "schema": { "type": "object", "required": [ "templates", "pagination" ], "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/TemplateStatus" }, "pageCount": { "type": "integer" }, "kind": { "type": "string", "enum": [ "TEMPLATE", "ADHOC" ] } } } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "tags": [ "Templates" ], "summary": "Create a template from a PDF", "description": "Creates a DRAFT template from a base64-encoded PDF. Add fields with `PUT /templates/{id}/fields`, then activate it before sending envelopes.", "operationId": "createTemplate", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "pdfBase64" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "pdfBase64": { "type": "string", "format": "byte", "description": "The PDF file, base64-encoded." } } } } } }, "responses": { "201": { "description": "Template created (DRAFT).", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/TemplateStatus" }, "pageCount": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates/{id}": { "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "get": { "tags": [ "Templates" ], "summary": "Get a template with its fields", "operationId": "getTemplate", "responses": { "200": { "description": "Template detail.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "$ref": "#/components/schemas/TemplateStatus" }, "pageCount": { "type": "integer" }, "fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "recipientRole": { "type": "string" }, "type": { "$ref": "#/components/schemas/FieldType" }, "label": { "type": "string", "nullable": true }, "page": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "required": { "type": "boolean" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates/{id}/fields": { "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "put": { "tags": [ "Templates" ], "summary": "Replace all fields on a DRAFT template", "description": "Replaces the template's full field set. Coordinates and sizes are fractions of the page (0..1), with the origin at the top-left.", "operationId": "setTemplateFields", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fields": { "type": "array", "items": { "type": "object", "required": [ "recipientRole", "type", "page", "x", "y", "width", "height" ], "properties": { "recipientRole": { "type": "string", "description": "Role that fills this field, e.g. \"signer1\"." }, "type": { "$ref": "#/components/schemas/FieldType" }, "label": { "type": "string" }, "page": { "type": "integer", "minimum": 1 }, "x": { "type": "number", "minimum": 0, "maximum": 1 }, "y": { "type": "number", "minimum": 0, "maximum": 1 }, "width": { "type": "number", "minimum": 0, "maximum": 1 }, "height": { "type": "number", "minimum": 0, "maximum": 1 }, "required": { "type": "boolean", "default": true } } } } } } } } }, "responses": { "200": { "description": "Fields replaced.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "fieldCount": { "type": "integer" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/templates/{id}/activate": { "parameters": [ { "$ref": "#/components/parameters/TemplateId" } ], "post": { "tags": [ "Templates" ], "summary": "Activate a template", "description": "Moves a DRAFT template (with at least one field) to ACTIVE so envelopes can be created from it.", "operationId": "activateTemplate", "responses": { "200": { "description": "Template activated.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ACTIVE" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "delete": { "tags": [ "Templates" ], "summary": "Archive a template", "operationId": "archiveTemplate", "responses": { "200": { "description": "Archive result. `ok` is false if the template was not found or already archived.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "status": { "type": "string", "enum": [ "ARCHIVED" ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "An API key created in Settings \u2192 API keys, e.g. `Authorization: Bearer sfk_...`." } }, "parameters": { "EnvelopeId": { "name": "id", "in": "path", "required": true, "description": "Envelope id.", "schema": { "type": "integer" } }, "TemplateId": { "name": "id", "in": "path", "required": true, "description": "Template id.", "schema": { "type": "integer" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key (max 200 chars) making this request safely retryable. The first successful response is stored and replayed on retries with `Idempotency-Replayed: true`. Failures are not cached.", "schema": { "type": "string", "maxLength": 200 } } }, "responses": { "BadRequest": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded (120 requests/minute per key).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable error message." }, "ref": { "type": "string", "description": "Correlation id for support, present on server-logged errors." } } }, "Pagination": { "type": "object", "properties": { "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "totalPages": { "type": "integer" } } }, "EnvelopeStatus": { "type": "string", "enum": [ "DRAFT", "SENT", "PARTIALLY_SIGNED", "COMPLETED", "DECLINED", "VOIDED", "EXPIRED" ] }, "RecipientStatus": { "type": "string", "enum": [ "PENDING", "VIEWED", "SIGNED", "DECLINED" ] }, "TemplateStatus": { "type": "string", "enum": [ "DRAFT", "ACTIVE", "ARCHIVED" ] }, "FieldType": { "type": "string", "enum": [ "SIGNATURE", "NAME", "DATE", "TEXT", "EMAIL", "CHECKBOX" ] }, "EnvelopeDetail": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "$ref": "#/components/schemas/EnvelopeStatus" }, "subject": { "type": "string", "nullable": true }, "signedPdfAvailable": { "type": "boolean" }, "recipients": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "status": { "$ref": "#/components/schemas/RecipientStatus" }, "signedAt": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }