{ "openapi": "3.0.0", "servers": [ { "url": "https://app.synexissign.com/api", "description": "Production" } ], "info": { "version": "1.1.0", "title": "Synexis Sign API", "description": "Synexis Sign API specs", "contact": { "name": "Synexis Sign", "email": "suporte@synexissign.com", "url": "https://synexissign.com" } }, "components": { "securitySchemes": { "AuthToken": { "type": "apiKey", "in": "header", "name": "X-Auth-Token" } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255, "example": "pedido-4711" }, "description": "Torna o retry seguro: se a MESMA chave voltar com o MESMO corpo, devolvemos a resposta original (marcada com o header `Idempotent-Replay: true`) em vez de executar de novo. Chave repetida com corpo diferente responde 422 `idempotency_key_reused`; requisicao ainda em processamento responde 409 `idempotency_in_progress` com `Retry-After: 5`. Guardada por 24h. Escopo: conta + usuario do token. Sem a chave, um retry de rede cria envelope duplicado — use um valor unico por operacao de negocio, e um valor NOVO para cada reenvio intencional (ex.: `::`). O replay reproduz o corpo ORIGINAL: URLs assinadas dentro dele (validade ~40 min) podem ja ter vencido — trate o replay como confirmacao da operacao, nao como fonte de links frescos (re-busque o recurso para obter URLs novas)." } }, "responses": { "TooManyRequests": { "description": "Rate limit por CONTA excedido (janela de 1 minuto). O teto vem do plano — 600 req/min no Profissional, 1200 no Empresarial — e pode ser menor em planos de franquia. Corpo: {\"status\":429,\"error\":\"Too many requests\",\"code\":\"rate_limited\"}. Re-tente respeitando o Retry-After. Toda resposta da API (2xx/4xx) traz X-RateLimit-*; quando o limitador esta em fail-open (Redis indisponivel) os headers ficam AUSENTES em vez de mentir.", "headers": { "X-RateLimit-Limit": { "schema": { "type": "integer" }, "description": "Teto da janela corrente do limitador que respondeu." }, "X-RateLimit-Remaining": { "schema": { "type": "integer" }, "description": "Requisicoes restantes na janela (0 num 429)." }, "X-RateLimit-Reset": { "schema": { "type": "integer" }, "description": "Quando a janela vira, em EPOCH segundos (estilo GitHub — nao e \"segundos restantes\")." }, "Retry-After": { "schema": { "type": "integer" }, "description": "Segundos ate a janela virar; espere isso antes de repetir." } } }, "Unauthorized": { "description": "Token ausente, invalido, de usuario arquivado ou de conta arquivada/suspensa. Corpo: {\"status\":401,\"error\":\"...\",\"code\":\"unauthenticated\"}." }, "Forbidden": { "description": "O plano da conta nao da direito a este recurso (features :api, :webhooks, :bulk_import…), ou o papel do usuario nao permite a acao. Corpo: {\"status\":403,\"error\":\"...\",\"code\":\"...\"} — codes: \"plan_upgrade_required\" (falta a feature no plano), \"forbidden\" (papel/recurso alheio) e \"forbidden.wrong_key_environment\" (chave de teste usada num recurso de producao, ou o inverso)." }, "UnprocessableEntity": { "description": "Payload invalido, cota do plano estourada, ou regra de negocio violada. Corpo: {\"status\":422,\"error\":\"\",\"code\":\"\"} — reaja pelo `code` (contrato estavel, ex.: \"invalid_parameter\", \"record_invalid\", \"idempotency_key_reused\"), nunca por match de string em `error`. Erros anteriores ao catalogo podem vir sem `code`." } } }, "tags": [ { "name": "Webhooks", "description": "Manage webhook endpoints that receive event notifications for form, submission and template events." }, { "name": "Events", "description": "Read streams of form and submission completion events." }, { "name": "Tools", "description": "Utility endpoints: merge PDFs and verify signed PDF documents." }, { "name": "Submissions", "description": "Signature requests can be initiated with Submissions API. Submissions can contain one submitter if signed by a single party or multiple submitters if the document template form contains signatures and fields to be collected and filled by multiple parties. Initiate new submissions to request signatures for specified submitters via email or phone number." }, { "name": "Submitters", "description": "Submitters API allows you to load all details provided by the signer of the document." }, { "name": "Templates", "description": "Templates represent reusable document signing forms with fields and signatures to be collected. It's possible to create unique template forms with fields and signatures using HTML or with tagged PDFs." }, { "name": "Contacts", "description": "Contacts are the account address book of signers (name, email and CPF). They power the recipient autocomplete and the \"Select from contacts\" picker when sending documents." }, { "name": "Certificates", "description": "Account certificate vault (ICP-Brasil). Read-only listing and asynchronous qualified signing. All endpoints respond 404 unless the certificate vault automation is enabled for the account." }, { "name": "Folders", "description": "Pastas da conta: listar e criar. Pastas organizam envelopes e modelos; \"Pai / Filha\" cria dois niveis." } ], "paths": { "/submissions/init": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Create a submission and return signing URLs", "description": "Creates a submission and returns its submitters including their signing URLs (does not require sending emails).", "operationId": "initSubmission", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template_id" ], "properties": { "template_id": { "type": "integer" }, "send_email": { "type": "boolean", "default": true }, "send_sms": { "type": "boolean", "default": false }, "send_whatsapp": { "type": "boolean", "default": false }, "submitters": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/templates/{id}/submissions": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Create submissions for a template", "description": "Creates one or more submissions for the given template.", "operationId": "createTemplateSubmissions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "send_email": { "type": "boolean", "default": true }, "send_sms": { "type": "boolean", "default": false }, "send_whatsapp": { "type": "boolean", "default": false }, "submitters": { "type": "array", "items": { "type": "object" } } } } } } }, "responses": { "201": { "description": "Created" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "List template submissions", "description": "Lists the submissions created from a given template. Same response shape and pagination as GET /submissions.", "operationId": "getTemplateSubmissions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the documents template.", "example": 1000001 }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "canceled", "declined", "expired", "sent", "opened", "partially_completed" ] }, "description": "Filter submissions by status. `sent` = enviado e ainda nao aberto; `opened` = aberto e nao concluido; `partially_completed` = parte dos signatarios concluiu, parte nao." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submissions based on submitters name, email or phone partial match." }, { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submissions by unique slug.", "example": "NtLDQM7eJX2ZMd" }, { "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submissions by template folder name." }, { "name": "author", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelos envios criados por um usuario da conta (e-mail exato do autor)." }, { "name": "signer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca por signatario: casa nome ou e-mail (parcial, sem diferenciar maiusculas) ou CPF (pelos digitos)." }, { "name": "empresa", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca pela empresa do signatario (parcial, sem diferenciar maiusculas)." }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela pasta do DOCUMENTO (a pasta canonica, que acompanha o documento quando ele e movido; inclui subpastas). Diferente de `template_folder`, que filtra pela pasta do modelo." }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados a partir desta data ou data-hora (ISO 8601, interpretada no fuso da conta)." }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados ate esta data (ISO 8601, no fuso da conta). O corte e sempre o FIM do dia informado (23:59:59) — hora enviada e ignorada." }, { "name": "completed_at_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Concluidos a partir desta data ou data-hora (ISO 8601, no fuso da conta). Implica envios com status `completed`." }, { "name": "completed_at_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Concluidos ate esta data (ISO 8601, no fuso da conta). O corte e sempre o FIM do dia informado (23:59:59) — hora enviada e ignorada. Implica envios com status `completed`." }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "slug", "status", "submitters_order", "audit_log_url", "completed_at", "created_at", "updated_at", "submitters", "created_by_user" ], "properties": { "id": { "type": "integer", "description": "Submission unique ID number." }, "name": { "type": "string", "description": "Name of the document submission", "example": "Test Submission Document" }, "source": { "type": "string", "description": "The source of the submission.", "enum": [ "invite", "bulk", "api", "embed", "link" ] }, "slug": { "type": "string", "description": "Unique slug of the submission." }, "status": { "type": "string", "description": "The status of the submission. Single ladder: completed > canceled > declined > expired > pending.", "enum": [ "completed", "canceled", "declined", "expired", "pending" ] }, "submitters_order": { "type": "string", "description": "The order of submitters.", "enum": [ "random", "preserved" ] }, "audit_log_url": { "type": "string", "nullable": true, "description": "Audit log file URL." }, "combined_document_url": { "type": "string", "nullable": true, "description": "Combined PDF file URL with documents and Audit Log." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submission was completed." }, "created_at": { "type": "string", "description": "The date and time when the submission was created." }, "updated_at": { "type": "string", "description": "The date and time when the submission was last updated." }, "archived_at": { "type": "string", "nullable": true, "description": "The date and time when the submission was archived." }, "submitters": { "type": "array", "description": "The list of submitters.", "items": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "status", "role", "metadata", "preferences" ], "properties": { "id": { "type": "integer", "description": "Submission unique ID number." }, "submission_id": { "type": "integer", "description": "Submission ID number." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "nullable": true, "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique key to be used in the form signing link and embedded form." }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined to complete the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "Submitter name." }, "phone": { "type": "string", "nullable": true, "description": "Submitter phone number." }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this submitter within your app." }, "status": { "type": "string", "description": "The status of signing request for the submitter.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "role": { "type": "string", "description": "The role of the submitter, matched to a template signing party by its name. Roles are customizable per account (Settings → Signer roles). When two parties share the same role name (e.g. two witnesses), match the submitter by `uuid` instead, since matching by `role` name resolves to the first matching party." }, "metadata": { "type": "object", "description": "Metadata object with additional submitter information." }, "preferences": { "type": "object", "description": "Object with submitter preferences." } } } }, "template": { "type": "object", "required": [ "id", "name", "external_id", "folder_name", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Template unique ID number." }, "name": { "type": "string", "description": "The name of the submission template." }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this template within your app." }, "folder_name": { "type": "string", "description": "Folder name where the template is located." }, "created_at": { "type": "string", "description": "The date and time when the submission template was created." }, "updated_at": { "type": "string", "description": "The date and time when the submission template was last updated." } } }, "created_by_user": { "type": "object", "nullable": true, "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the user who created the submission." }, "first_name": { "type": "string", "description": "The first name of the user who created the submission." }, "last_name": { "type": "string", "description": "The last name of the user who created the submission." }, "email": { "type": "string", "description": "The email address of the user who created the submission." } } } } } }, "pagination": { "type": "object", "required": [ "count", "next", "prev" ], "properties": { "count": { "type": "integer", "description": "Submissions count." }, "next": { "type": "integer", "nullable": true, "description": "The ID of the submission after which the next page starts." }, "prev": { "type": "integer", "nullable": true, "description": "The ID of the submission before which the previous page ends." } } } } }, "example": { "data": [ { "id": 1, "name": null, "source": "link", "submitters_order": "random", "slug": "VyL4szTwYoSvXq", "status": "completed", "audit_log_url": "https://app.synexissign.com/file/hash/example.pdf", "combined_document_url": null, "expire_at": null, "completed_at": "2023-12-10T15:49:21.895Z", "created_at": "2023-12-10T15:48:17.166Z", "updated_at": "2023-12-10T15:49:21.895Z", "archived_at": null, "submitters": [ { "id": 1, "submission_id": 1, "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "email": "submitter@example.com", "slug": "dsEeWrhRD8yDXT", "sent_at": "2023-12-14T15:45:49.011Z", "opened_at": "2023-12-14T15:48:23.011Z", "completed_at": "2023-12-14T15:49:21.701Z", "declined_at": null, "created_at": "2023-12-10T15:48:17.173Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "John Doe", "phone": "+1234567890", "status": "completed", "role": "First Party", "metadata": {}, "preferences": {} } ], "template": { "id": 1, "name": "Example Template", "external_id": "Temp123", "folder_name": "Default", "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z" }, "created_by_user": { "id": 1, "first_name": "Bob", "last_name": "Smith", "email": "bob.smith@example.com" } } ], "pagination": { "count": 1, "next": 1, "prev": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/{id}/bulk": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Bulk create submissions from CSV/XLSX", "description": "Creates submissions in bulk from a CSV string or a base64-encoded spreadsheet. Requires the bulk_import plan feature.", "operationId": "bulkCreateSubmissions", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "csv": { "type": "string", "description": "Raw CSV text." }, "file": { "type": "string", "format": "byte", "description": "base64-encoded CSV or XLSX." }, "filename": { "type": "string", "description": "Used to detect format when sending file." } } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "submissions_count": { "type": "integer" }, "submitters_count": { "type": "integer" }, "submissions": { "type": "array", "items": { "type": "object" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/user": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Get current user", "description": "Returns the authenticated API user.", "operationId": "getUser", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "environment": { "type": "string", "enum": [ "production", "sandbox" ], "description": "Ambiente da chave usada na request: 'sandbox' quando o token pertence a conta de teste vinculada, 'production' caso contrario." } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "Returns the list of webhook endpoints configured for the account.", "operationId": "getWebhooks", "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Webhooks" ], "summary": "Create a webhook", "description": "Creates a webhook endpoint. Requires the webhooks plan feature. The URL is validated against SSRF (internal addresses are blocked).", "operationId": "createWebhook", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "example": "https://example.com/webhooks" }, "events": { "type": "array", "description": "Eventos assinados por este endpoint. Os tres ultimos sao ADMINISTRATIVOS da conta (integracao CRM): subscription.updated sai quando plano, status ou cota custom mudam; quota.warning quando o consumo cruza 80% da franquia do mes; quota.exceeded quando um envio e recusado por franquia esgotada. Os dois de quota saem no maximo UMA vez por periodo.", "items": { "type": "string", "enum": [ "form.viewed", "form.started", "form.completed", "form.declined", "submission.created", "submission.completed", "submission.expired", "submission.archived", "submission.canceled", "template.created", "template.updated", "template.archived", "subscription.updated", "quota.warning", "quota.exceeded" ] } } } } } } }, "responses": { "201": { "description": "Created" }, "422": { "description": "Validation/SSRF error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/webhooks/{id}": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Webhooks" ], "summary": "Get a webhook", "operationId": "getWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "security": [ { "AuthToken": [] } ], "tags": [ "Webhooks" ], "summary": "Update a webhook", "operationId": "updateWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" }, "events": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "OK" }, "422": { "description": "Validation/SSRF error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "security": [ { "AuthToken": [] } ], "tags": [ "Webhooks" ], "summary": "Delete a webhook", "operationId": "deleteWebhook", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{id}/rotate_secret": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Webhooks" ], "summary": "Rotate the webhook signing secret", "description": "Gera um `hmac_secret` novo para o endpoint e o devolve na resposta. Use quando o segredo vazar ou por politica de rotacao — antes disto a unica saida era apagar o webhook e criar outro, perdendo o historico de entregas.\n\nA troca vale a partir da PROXIMA entrega: as que ja estao na fila foram assinadas com o segredo antigo e serao rejeitadas por um verificador que so conheca o novo. Para um corte limpo, aceite os dois segredos por alguns minutos.\n\nCom `Idempotency-Key`: o replay devolve o segredo daquela execucao. Se voce rotacionar DE NOVO com outra chave, o replay da chave antiga passa a devolver um segredo obsoleto — confie sempre na resposta da rotacao mais recente.", "operationId": "rotateWebhookSecret", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the webhook.", "example": 1 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "O webhook com o `hmac_secret` novo." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/webhooks/{id}/events": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Webhooks" ], "summary": "List webhook delivery attempts", "description": "Historico de ENTREGAS do endpoint: um registro por evento, com o resultado de cada tentativa (status HTTP e corpo truncado). Responde \"o evento chegou?\" sem abrir o painel.\n\nA entrega re-tenta com backoff exponencial — 12 tentativas (~5,7 dias) para `form.completed`, 10 (~34h) para os demais. O historico e purgado apos 90 dias (`WEBHOOK_EVENTS_RETENTION_DAYS`); para guardar mais tempo, persista do seu lado ao receber.\n\nNao devolve o payload enviado: ele e reconstruivel a partir do proprio recurso, e repeti-lo aqui duplicaria dado de signatario num endpoint de diagnostico. O `uuid` de cada evento e o MESMO valor entregue no header X-Synexis-Event-Id do webhook — estavel entre re-tentativas, reenvios manuais e entre os endpoints da conta; use-o para casar o feed com as entregas recebidas. Excecao: um header customizado homonimo cadastrado no endpoint substitui o nosso — nesse caso o valor recebido nao e este uuid (nao cadastre headers com esse nome).", "operationId": "getWebhookEvents", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the webhook.", "example": 1 }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the delivery to start the list from." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The number of deliveries to return. Default value is 10. Maximum value is 100." } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Identificador do evento; re-tentativas compartilham o mesmo uuid." }, "event_type": { "type": "string", "example": "submission.completed" }, "status": { "type": "string", "description": "pending, success ou error.", "example": "success" }, "record_type": { "type": "string", "example": "Submission" }, "record_id": { "type": "integer", "example": 1001 }, "created_at": { "type": "string", "format": "date-time" }, "attempts": { "type": "array", "items": { "type": "object", "properties": { "attempt": { "type": "integer", "example": 1 }, "response_status_code": { "type": "integer", "description": "0 quando o destino foi bloqueado (anti-SSRF) ou inalcancavel.", "example": 200 }, "response_body": { "type": "string", "description": "Corpo da resposta, truncado." }, "created_at": { "type": "string", "format": "date-time" } } } } } } }, "pagination": { "type": "object", "properties": { "count": { "type": "integer", "example": 10 }, "next": { "type": "integer", "nullable": true, "example": 4532 }, "prev": { "type": "integer", "nullable": true, "example": 4545 } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/contacts": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Contacts" ], "summary": "List contacts", "description": "Returns the account address book of signers. Supports cursor pagination (after/before) and a search query.", "operationId": "getContacts", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Search by name, email or CPF digits." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Contacts" ], "summary": "Create a contact", "description": "Creates a contact. Name, email and a valid CPF are required; empresa (company) is optional.", "operationId": "createContact", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "contact" ], "properties": { "contact": { "type": "object", "required": [ "name", "email", "cpf" ], "properties": { "name": { "type": "string", "example": "Maria Silva" }, "email": { "type": "string", "example": "maria@example.com" }, "cpf": { "type": "string", "example": "077.563.529-47" }, "empresa": { "type": "string", "example": "ACME Ltda" } } } } } } } }, "responses": { "201": { "description": "Created" }, "422": { "description": "Validation error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/contacts/{id}": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Contacts" ], "summary": "Get a contact", "operationId": "getContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "OK" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "security": [ { "AuthToken": [] } ], "tags": [ "Contacts" ], "summary": "Update a contact", "operationId": "updateContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "contact": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "cpf": { "type": "string" }, "empresa": { "type": "string" } } } } } } } }, "responses": { "200": { "description": "OK" }, "422": { "description": "Validation error" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "security": [ { "AuthToken": [] } ], "tags": [ "Contacts" ], "summary": "Delete a contact", "operationId": "deleteContact", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Deleted" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tools/merge": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Tools" ], "summary": "Merge PDF files", "description": "Merges two or more base64-encoded PDF files into a single PDF.", "operationId": "mergeTools", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "string", "format": "byte" }, "minItems": 2 } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "string", "description": "base64-encoded merged PDF" } } } } } }, "422": { "description": "At least two files are required" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/tools/verify": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Tools" ], "summary": "Verify a signed PDF", "description": "Verifies signatures of a base64-encoded PDF and returns signature metadata.", "operationId": "verifyTools", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "byte" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "checksum_status": { "type": "string" }, "signatures": { "type": "array", "items": { "type": "object" } } } } } } }, "422": { "description": "Malformed PDF" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ] } }, "/events/form/{type}": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Events" ], "summary": "List form events", "description": "Reconciliation feed of signer-level facts, paginated by the fact timestamp (cursor via `after`/`before`). Each item carries a deterministic `id` — the same `id` delivered in the signed webhook body for that fact — so you can deduplicate and backfill missed webhooks.", "operationId": "getFormEvents", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "form.completed", "form.declined" ] }, "description": "Event type. `form.viewed`/`form.started` are not served: they have no single re-derivable fact.", "example": "form.completed" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Exclusive UPPER bound (unix timestamp): returns facts strictly older than this. Use the `next` cursor from the previous page. Pages may overlap at second boundaries — deduplicate by `id`." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Exclusive LOWER bound (unix timestamp): returns facts strictly newer than this. Use the `prev` cursor from the previous page. Pages may overlap at second boundaries — deduplicate by `id`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deterministic event id (UUIDv5 of the fact) — equals the `id` in the signed webhook body delivered for the same fact." }, "event_type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the fact happened (not when any webhook was delivered)." }, "data": { "type": "object", "description": "Snapshot of the record at read time — same serializer as the corresponding webhook." } } } }, "pagination": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "integer", "nullable": true, "description": "Cursor for the next (older) page — pass as `after`. Second-precision: consecutive pages may overlap at the boundary; deduplicate by `id`." }, "prev": { "type": "integer", "nullable": true, "description": "Cursor for newer items — pass as `before`. Second-precision: pages may overlap at the boundary; deduplicate by `id`." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/events/submission/{type}": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Events" ], "summary": "List submission events", "description": "Reconciliation feed of the submission's terminal facts, paginated by the fact timestamp (cursor via `after`/`before`). Each item carries a deterministic `id` — the same `id` delivered in the signed webhook body for that fact — so you can deduplicate and backfill missed webhooks with 4 cursor calls instead of polling each submission. `submission.expired` lists submissions whose deadline passed while signatures were still pending (canceled ones excluded — `canceled` outranks `expired` in the status ladder; submissions archived BEFORE the deadline are excluded too, since no webhook fired for them, while archiving AFTER expiry does not remove the fact). The feed derives facts from CURRENT state: a fact that was later undone or superseded (an unarchived submission, a qualified signature completed after the deadline) leaves the feed — the final state prevails.", "operationId": "getSubmissionEvents", "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "submission.completed", "submission.canceled", "submission.expired", "submission.archived" ] }, "description": "Event type (a terminal fact of the submission lifecycle).", "example": "submission.completed" }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Exclusive UPPER bound (unix timestamp): returns facts strictly older than this. Use the `next` cursor from the previous page. Pages may overlap at second boundaries — deduplicate by `id`." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Exclusive LOWER bound (unix timestamp): returns facts strictly newer than this. Use the `prev` cursor from the previous page. Pages may overlap at second boundaries — deduplicate by `id`." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Deterministic event id (UUIDv5 of the fact) — equals the `id` in the signed webhook body delivered for the same fact." }, "event_type": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time", "description": "When the fact happened (not when any webhook was delivered)." }, "data": { "type": "object", "description": "Snapshot of the record at read time — same serializer as the corresponding webhook." } } } }, "pagination": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "integer", "nullable": true, "description": "Cursor for the next (older) page — pass as `after`. Second-precision: consecutive pages may overlap at the boundary; deduplicate by `id`." }, "prev": { "type": "integer", "nullable": true, "description": "Cursor for newer items — pass as `before`. Second-precision: pages may overlap at the boundary; deduplicate by `id`." } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "List all templates", "description": "The API endpoint provides the ability to retrieve a list of available document templates.", "operationId": "getTemplates", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter templates based on the name partial match." }, { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter templates by unique slug.", "example": "opaKWh8WWTAcVG" }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The unique applications-specific identifier provided for the template via API or Embedded template form builder. It allows you to receive only templates with your specified external id." }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter templates by folder name." }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Get only archived templates instead of active ones." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The number of templates to return. Default value is 10. Maximum value is 100." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the template to start the list from. It allows you to receive only templates with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of templates." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the template to end the list with. It allows you to receive only templates with id less than the specified value." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "description": "List of templates.", "items": { "type": "object", "required": [ "id", "slug", "name", "preferences", "schema", "fields", "submitters", "author_id", "created_at", "updated_at", "source", "external_id", "folder_id", "folder_name", "author", "documents" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document template." }, "slug": { "type": "string", "description": "Unique slug of the document template." }, "name": { "type": "string", "description": "Name of the template." }, "preferences": { "type": "object", "description": "Template preferences." }, "schema": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "attachment_uuid", "name" ], "properties": { "attachment_uuid": { "type": "string", "description": "Unique indentifier of attached document to the template." }, "name": { "type": "string", "description": "Name of the attached document to the template." } } } }, "fields": { "type": "array", "description": "List of fields to be filled in the template.", "items": { "type": "object", "required": [ "uuid", "submitter_uuid", "name", "type", "required", "areas" ], "properties": { "uuid": { "type": "string", "description": "Unique identifier of the field." }, "submitter_uuid": { "type": "string", "description": "Unique identifier of the submitter that filled the field." }, "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels." }, "font_type": { "type": "string", "description": "Font type of the field value." }, "font": { "type": "string", "description": "Font family of the field value." }, "color": { "type": "string", "description": "Font color of the field value." }, "background": { "type": "string", "description": "Field box background color." }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." }, "valign": { "type": "string", "description": "Vertical alignment of the field text value." }, "format": { "type": "string", "description": "The data format for different field types." }, "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } }, "areas": { "type": "array", "description": "List of areas where the field is located in the document.", "items": { "type": "object", "required": [ "x", "y", "w", "h", "attachment_uuid", "page" ], "properties": { "x": { "type": "number", "description": "X coordinate of the area where the field is located in the document." }, "y": { "type": "number", "description": "Y coordinate of the area where the field is located in the document." }, "w": { "type": "number", "description": "Width of the area where the field is located in the document." }, "h": { "type": "number", "description": "Height of the area where the field is located in the document." }, "attachment_uuid": { "type": "string", "description": "Unique identifier of the attached document where the field is located." }, "page": { "type": "integer", "description": "Page number of the attached document where the field is located." } } } } } } }, "submitters": { "type": "array", "items": { "type": "object", "required": [ "name", "uuid" ], "properties": { "name": { "type": "string", "description": "Submitter name." }, "uuid": { "type": "string", "description": "Unique identifier of the submitter." } } } }, "author_id": { "type": "integer", "description": "Unique identifier of the author of the template." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the template was archived." }, "created_at": { "type": "string", "description": "Date and time when the template was created." }, "updated_at": { "type": "string", "description": "Date and time when the template was updated." }, "source": { "type": "string", "description": "Source of the template.", "enum": [ "native", "api", "embed" ] }, "external_id": { "type": "string", "nullable": true, "description": "Identifier of the template in the external system." }, "folder_id": { "type": "integer", "description": "Unique identifier of the folder where the template is placed." }, "folder_name": { "type": "string", "description": "Folder name where the template is placed." }, "author": { "type": "object", "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the author." }, "first_name": { "type": "string", "description": "First name of the author." }, "last_name": { "type": "string", "description": "Last name of the author." }, "email": { "type": "string", "description": "Author email." } } }, "documents": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "id", "uuid", "url", "preview_image_url", "filename" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document." }, "uuid": { "type": "string", "description": "Unique identifier of the document." }, "url": { "type": "string", "description": "URL of the document." }, "preview_image_url": { "type": "string", "description": "Document preview image URL." }, "filename": { "type": "string", "description": "Document filename." } } } } } } }, "pagination": { "type": "object", "required": [ "count", "next", "prev" ], "properties": { "count": { "type": "integer", "description": "Templates count." }, "next": { "type": "integer", "nullable": true, "description": "The ID of the template after which the next page starts." }, "prev": { "type": "integer", "nullable": true, "description": "The ID of the template before which the previous page ends." } } } } }, "example": { "data": [ { "id": 1, "slug": "iRgjDX7WDK6BRo", "name": "Example Template", "preferences": {}, "schema": [ { "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", "name": "example-document" } ], "fields": [ { "uuid": "594bdf04-d941-4ca6-aa73-93e61d625c02", "submitter_uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "name": "Full Name", "type": "text", "required": true, "preferences": {}, "areas": [ { "x": 0.2638888888888889, "y": 0.168958742632613, "w": 0.325, "h": 0.04616895874263263, "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", "page": 0 } ] } ], "submitters": [ { "name": "First Party", "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0" } ], "author_id": 1, "archived_at": null, "created_at": "2023-12-14T15:21:57.375Z", "updated_at": "2023-12-14T15:22:55.094Z", "source": "native", "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", "author": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, "documents": [ { "id": 5, "uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", "url": "https://app.synexissign.com/file/hash/sample-document.pdf", "preview_image_url": "https://app.synexissign.com/file/hash/0.jpg", "filename": "example-document.pdf" } ] } ], "pagination": { "count": 1, "next": 1, "prev": 2 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/{id}": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Get a template", "description": "The API endpoint provides the functionality to retrieve information about a document template.", "operationId": "getTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the document template.", "example": 1000001 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "preferences", "schema", "fields", "submitters", "author_id", "archived_at", "created_at", "updated_at", "source", "external_id", "folder_id", "folder_name", "author", "documents" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document template." }, "slug": { "type": "string", "description": "Unique slug of the document template." }, "name": { "type": "string", "description": "Name of the template." }, "preferences": { "type": "object", "description": "Template preferences." }, "schema": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "attachment_uuid", "name" ], "properties": { "attachment_uuid": { "type": "string", "description": "Unique indentifier of attached document to the template." }, "name": { "type": "string", "description": "Name of the attached document to the template." } } } }, "fields": { "type": "array", "description": "List of fields to be filled in the template.", "items": { "type": "object", "required": [ "uuid", "submitter_uuid", "name", "type", "required", "areas" ], "properties": { "uuid": { "type": "string", "description": "Unique identifier of the field." }, "submitter_uuid": { "type": "string", "description": "Unique identifier of the submitter that filled the field." }, "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels." }, "font_type": { "type": "string", "description": "Font type of the field value." }, "font": { "type": "string", "description": "Font family of the field value." }, "color": { "type": "string", "description": "Font color of the field value." }, "background": { "type": "string", "description": "Field box background color." }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." }, "valign": { "type": "string", "description": "Vertical alignment of the field text value." }, "format": { "type": "string", "description": "The data format for different field types." }, "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } }, "areas": { "type": "array", "description": "List of areas where the field is located in the document.", "items": { "type": "object", "required": [ "x", "y", "w", "h", "attachment_uuid", "page" ], "properties": { "x": { "type": "number", "description": "X coordinate of the area where the field is located in the document." }, "y": { "type": "number", "description": "Y coordinate of the area where the field is located in the document." }, "w": { "type": "number", "description": "Width of the area where the field is located in the document." }, "h": { "type": "number", "description": "Height of the area where the field is located in the document." }, "attachment_uuid": { "type": "string", "description": "Unique identifier of the attached document where the field is located." }, "page": { "type": "integer", "description": "Page number of the attached document where the field is located." } } } } } } }, "submitters": { "type": "array", "items": { "type": "object", "required": [ "name", "uuid" ], "properties": { "name": { "type": "string", "description": "Submitter name." }, "uuid": { "type": "string", "description": "Unique identifier of the submitter." } } } }, "author_id": { "type": "integer", "description": "Unique identifier of the author of the template." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the template was archived." }, "created_at": { "type": "string", "description": "Date and time when the template was created." }, "updated_at": { "type": "string", "description": "Date and time when the template was updated." }, "source": { "type": "string", "description": "Source of the template.", "enum": [ "native", "api", "embed" ] }, "external_id": { "type": "string", "nullable": true, "description": "Identifier of the template in the external system." }, "folder_id": { "type": "integer", "description": "Unique identifier of the folder where the template is placed." }, "folder_name": { "type": "string", "description": "Folder name where the template is placed." }, "author": { "type": "object", "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the author." }, "first_name": { "type": "string", "description": "First name of the author." }, "last_name": { "type": "string", "description": "Last name of the author." }, "email": { "type": "string", "description": "Author email." } } }, "documents": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "id", "uuid", "url", "preview_image_url", "filename" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document." }, "uuid": { "type": "string", "description": "Unique identifier of the document." }, "url": { "type": "string", "description": "URL of the document." }, "preview_image_url": { "type": "string", "description": "Document preview image URL." }, "filename": { "type": "string", "description": "Document filename." } } } } } }, "example": { "id": 1, "slug": "iRgjDX7WDK6BRo", "name": "Example Template", "preferences": {}, "schema": [ { "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", "name": "example-document" } ], "fields": [ { "uuid": "594bdf04-d941-4ca6-aa73-93e61d625c02", "submitter_uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "name": "Full Name", "type": "text", "required": true, "preferences": {}, "areas": [ { "x": 0.2638888888888889, "y": 0.168958742632613, "w": 0.325, "h": 0.04616895874263263, "attachment_uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", "page": 0 } ] } ], "submitters": [ { "name": "First Party", "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0" } ], "author_id": 1, "archived_at": null, "created_at": "2023-12-14T15:21:57.375Z", "updated_at": "2023-12-14T15:22:55.094Z", "source": "native", "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", "author": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, "documents": [ { "id": 5, "uuid": "d94e615f-76e3-46d5-8f98-36bdacb8664a", "url": "https://app.synexissign.com/file/hash/sample-document.pdf", "preview_image_url": "https://app.synexissign.com/file/hash/0.jpg", "filename": "example-document.pdf" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Archive a template", "description": "The API endpoint allows you to archive a document template.", "operationId": "archiveTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the document template.", "example": 1000001 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "archived_at" ], "properties": { "id": { "type": "integer", "description": "Template unique ID number." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the template was archived." } } }, "example": { "id": 1, "archived_at": "2023-12-14T15:50:21.799Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Update a template", "description": "The API endpoint provides the functionality to move a document template to a different folder and update the name of the template.", "operationId": "updateTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the document template.", "example": 1000001 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the template", "example": "New Document Name" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be moved.", "example": "New Folder" }, "roles": { "type": "array", "description": "An array of submitter role names to update the template with.", "items": { "type": "string" }, "example": [ "Agent", "Customer" ] }, "archived": { "type": "boolean", "description": "Set `false` to unarchive template." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Template unique ID number." }, "updated_at": { "type": "string", "description": "Date and time when the template was last updated." } } }, "example": { "id": 1, "updated_at": "2023-12-14T15:50:21.799Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submissions": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "List all submissions", "description": "The API endpoint provides the ability to retrieve a list of available submissions.", "operationId": "getSubmissions", "parameters": [ { "name": "template_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The template ID allows you to receive only the submissions created from that specific template." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "pending", "completed", "canceled", "declined", "expired", "sent", "opened", "partially_completed" ] }, "description": "Filter submissions by status. `sent` = enviado e ainda nao aberto; `opened` = aberto e nao concluido; `partially_completed` = parte dos signatarios concluiu, parte nao." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submissions based on submitters name, email or phone partial match." }, { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submissions by unique slug.", "example": "NtLDQM7eJX2ZMd" }, { "name": "template_folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submissions by template folder name." }, { "name": "author", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pelos envios criados por um usuario da conta (e-mail exato do autor)." }, { "name": "signer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca por signatario: casa nome ou e-mail (parcial, sem diferenciar maiusculas) ou CPF (pelos digitos)." }, { "name": "empresa", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Busca pela empresa do signatario (parcial, sem diferenciar maiusculas)." }, { "name": "folder", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filtra pela pasta do DOCUMENTO (a pasta canonica, que acompanha o documento quando ele e movido; inclui subpastas). Diferente de `template_folder`, que filtra pela pasta do modelo." }, { "name": "created_at_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados a partir desta data ou data-hora (ISO 8601, interpretada no fuso da conta)." }, { "name": "created_at_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Criados ate esta data (ISO 8601, no fuso da conta). O corte e sempre o FIM do dia informado (23:59:59) — hora enviada e ignorada." }, { "name": "completed_at_from", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Concluidos a partir desta data ou data-hora (ISO 8601, no fuso da conta). Implica envios com status `completed`." }, { "name": "completed_at_to", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Concluidos ate esta data (ISO 8601, no fuso da conta). O corte e sempre o FIM do dia informado (23:59:59) — hora enviada e ignorada. Implica envios com status `completed`." }, { "name": "archived", "in": "query", "required": false, "schema": { "type": "boolean" }, "description": "Returns only archived submissions when `true` and only active submissions when `false`." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The number of submissions to return. Default value is 10. Maximum value is 100." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the submission to start the list from. It allows you to receive only submissions with an ID greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submissions." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the submission that marks the end of the list. It allows you to receive only submissions with an ID less than the specified value." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "source", "slug", "status", "submitters_order", "audit_log_url", "completed_at", "created_at", "updated_at", "submitters", "created_by_user" ], "properties": { "id": { "type": "integer", "description": "Submission unique ID number." }, "name": { "type": "string", "description": "Name of the document submission", "example": "Test Submission Document" }, "source": { "type": "string", "description": "The source of the submission.", "enum": [ "invite", "bulk", "api", "embed", "link" ] }, "slug": { "type": "string", "description": "Unique slug of the submission." }, "status": { "type": "string", "description": "The status of the submission. Single ladder: completed > canceled > declined > expired > pending.", "enum": [ "completed", "canceled", "declined", "expired", "pending" ] }, "submitters_order": { "type": "string", "description": "The order of submitters.", "enum": [ "random", "preserved" ] }, "audit_log_url": { "type": "string", "nullable": true, "description": "Audit log file URL." }, "combined_document_url": { "type": "string", "nullable": true, "description": "Combined PDF file URL with documents and Audit Log." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submission was completed." }, "created_at": { "type": "string", "description": "The date and time when the submission was created." }, "updated_at": { "type": "string", "description": "The date and time when the submission was last updated." }, "archived_at": { "type": "string", "nullable": true, "description": "The date and time when the submission was archived." }, "submitters": { "type": "array", "description": "The list of submitters.", "items": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "status", "role", "metadata", "preferences" ], "properties": { "id": { "type": "integer", "description": "Submission unique ID number." }, "submission_id": { "type": "integer", "description": "Submission ID number." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "nullable": true, "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique key to be used in the form signing link and embedded form." }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined to complete the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "Submitter name." }, "phone": { "type": "string", "nullable": true, "description": "Submitter phone number." }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this submitter within your app." }, "status": { "type": "string", "description": "The status of signing request for the submitter.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "role": { "type": "string", "description": "The role of the submitter, matched to a template signing party by its name. Roles are customizable per account (Settings → Signer roles). When two parties share the same role name (e.g. two witnesses), match the submitter by `uuid` instead, since matching by `role` name resolves to the first matching party." }, "metadata": { "type": "object", "description": "Metadata object with additional submitter information." }, "preferences": { "type": "object", "description": "Object with submitter preferences." } } } }, "template": { "type": "object", "required": [ "id", "name", "external_id", "folder_name", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Template unique ID number." }, "name": { "type": "string", "description": "The name of the submission template." }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this template within your app." }, "folder_name": { "type": "string", "description": "Folder name where the template is located." }, "created_at": { "type": "string", "description": "The date and time when the submission template was created." }, "updated_at": { "type": "string", "description": "The date and time when the submission template was last updated." } } }, "created_by_user": { "type": "object", "nullable": true, "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the user who created the submission." }, "first_name": { "type": "string", "description": "The first name of the user who created the submission." }, "last_name": { "type": "string", "description": "The last name of the user who created the submission." }, "email": { "type": "string", "description": "The email address of the user who created the submission." } } } } } }, "pagination": { "type": "object", "required": [ "count", "next", "prev" ], "properties": { "count": { "type": "integer", "description": "Submissions count." }, "next": { "type": "integer", "nullable": true, "description": "The ID of the submission after which the next page starts." }, "prev": { "type": "integer", "nullable": true, "description": "The ID of the submission before which the previous page ends." } } } } }, "example": { "data": [ { "id": 1, "name": null, "source": "link", "submitters_order": "random", "slug": "VyL4szTwYoSvXq", "status": "completed", "audit_log_url": "https://app.synexissign.com/file/hash/example.pdf", "combined_document_url": null, "expire_at": null, "completed_at": "2023-12-10T15:49:21.895Z", "created_at": "2023-12-10T15:48:17.166Z", "updated_at": "2023-12-10T15:49:21.895Z", "archived_at": null, "submitters": [ { "id": 1, "submission_id": 1, "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "email": "submitter@example.com", "slug": "dsEeWrhRD8yDXT", "sent_at": "2023-12-14T15:45:49.011Z", "opened_at": "2023-12-14T15:48:23.011Z", "completed_at": "2023-12-14T15:49:21.701Z", "declined_at": null, "created_at": "2023-12-10T15:48:17.173Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "John Doe", "phone": "+1234567890", "status": "completed", "role": "First Party", "metadata": {}, "preferences": {} } ], "template": { "id": 1, "name": "Example Template", "external_id": "Temp123", "folder_name": "Default", "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z" }, "created_by_user": { "id": 1, "first_name": "Bob", "last_name": "Smith", "email": "bob.smith@example.com" } } ], "pagination": { "count": 1, "next": 1, "prev": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Create a submission", "description": "This API endpoint allows you to create signature requests (submissions) for a document template and send them to the specified submitters (signers).
Related Guides
Send documents for signature via API
Pre-fill PDF document form fields with API", "operationId": "createSubmission", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template_id", "submitters" ], "properties": { "template_id": { "type": "integer", "description": "The unique identifier of the template. Document template forms can be created via the Web UI, PDF and DOCX API, or HTML API.", "example": 1000001 }, "send_email": { "type": "boolean", "description": "Set `false` to disable signature request emails sending.", "default": true }, "send_sms": { "type": "boolean", "description": "Set `true` to send signature request via phone number and SMS.", "default": false }, "send_whatsapp": { "type": "boolean", "description": "Set `true` to send the signature request via WhatsApp to the submitter's phone number.", "default": false }, "order": { "type": "string", "description": "Pass 'random' to send signature request emails to all parties right away. The order is 'preserved' by default so the second party will receive a signature request email only after the document is signed by the first party.", "default": "preserved", "enum": [ "preserved", "random" ] }, "completed_redirect_url": { "type": "string", "description": "Specify URL to redirect to after the submission completion." }, "bcc_completed": { "type": "string", "description": "Specify BCC address to send signed documents to after the completion." }, "reply_to": { "type": "string", "description": "Specify Reply-To address to use in the notification emails." }, "expire_at": { "type": "string", "description": "Specify the expiration date and time after which the submission becomes unavailable for signature.", "example": "2024-09-01 12:00:00 UTC" }, "message": { "type": "object", "properties": { "subject": { "type": "string", "description": "Custom signature request email subject." }, "body": { "type": "string", "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." } } }, "submitters": { "type": "array", "description": "The list of submitters for the submission.", "items": { "type": "object", "required": [ "email" ], "properties": { "name": { "type": "string", "description": "The name of the submitter." }, "role": { "type": "string", "description": "The role name or title of the submitter, matched to a template signing party by its name. Roles are customizable per account (Settings → Signer roles). When two parties share the same role name (e.g. two witnesses), match by `uuid` instead, since matching by `role` name resolves to the first matching party.", "example": "First Party" }, "email": { "type": "string", "description": "The email address of the submitter.", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "The phone number of the submitter, formatted according to the E.164 standard.", "example": "+1234567890" }, "phone_country": { "type": "string", "enum": [ "BR" ], "description": "Converte um numero NACIONAL para E.164 usando o DDI do pais indicado (ex.: 'BR'). So converte com o pedido explicito — a API nunca infere DDI; numero ja internacional ('+...') passa intacto. Para BR: o 0 de tronco inicial e descartado e o numero deve ter 10-11 digitos (fora disso, 422 — inclusive numero que ja embute o 55 sem '+'). Sem este campo, telefone sem '+' e 422." }, "empresa": { "type": "string", "description": "Company of the submitter (optional).", "example": "Acme Ltda" }, "cpf": { "type": "string", "description": "CPF (Brazilian taxpayer ID) of the submitter - digits or formatted. Required to complete the signature; for POST /api/submissions/emails and invited signers it is collected on the signing screen.", "example": "07756352947" }, "values": { "type": "object", "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." }, "external_id": { "type": "string", "description": "Your application-specific unique string key to identify this submitter within your app." }, "completed": { "type": "boolean", "description": "Pass `true` to mark submitter as completed and auto-signed via API." }, "metadata": { "type": "object", "description": "Metadata object with additional submitter information.", "example": "{ \"customField\": \"value\" }" }, "send_email": { "type": "boolean", "description": "Set `false` to disable signature request emails sending only for this submitter.", "default": true }, "send_sms": { "type": "boolean", "description": "Set `true` to send signature request via phone number and SMS.", "default": false }, "send_whatsapp": { "type": "boolean", "description": "Set `true` to send the signature request via WhatsApp to the submitter's phone number.", "default": false }, "reply_to": { "type": "string", "description": "Specify Reply-To address to use in the notification emails for this submitter." }, "completed_redirect_url": { "type": "string", "description": "Submitter specific URL to redirect to after the submission completion." }, "order": { "type": "integer", "description": "The order of the submitter in the workflow (e.g., 0 for the first signer, 1 for the second, etc.). Use the same order number to create order groups. By default, submitters are ordered as in the submitters array." }, "require_phone_2fa": { "type": "boolean", "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, "require_email_2fa": { "type": "boolean", "description": "Set to `true` to require email 2FA verification via a one-time code sent to the email address in order to access the documents.", "default": false }, "message": { "type": "object", "properties": { "subject": { "type": "string", "description": "Custom signature request email subject for the submitter." }, "body": { "type": "string", "description": "Custom signature request email body for the submitter. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." } } }, "fields": { "type": "array", "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Document template field name.", "example": "First Name" }, "default_value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", "example": "Acme" }, "readonly": { "type": "boolean", "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", "default": false }, "required": { "type": "boolean", "description": "Set `true` to make the field required." }, "title": { "type": "string", "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." }, "description": { "type": "string", "description": "Field description displayed on the signing form. Supports Markdown." }, "validation": { "type": "object", "properties": { "pattern": { "type": "string", "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", "example": "[A-Z]{4}" }, "message": { "type": "string", "description": "A custom error message to display on validation failure." }, "min": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Minimum allowed number value or date depending on field type." }, "max": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Maximum allowed number value or date depending on field type." }, "step": { "type": "number", "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." } } }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels.", "example": 12 }, "font_type": { "type": "string", "description": "Font type of the field value.", "enum": [ "bold", "italic", "bold_italic" ] }, "font": { "type": "string", "description": "Font family of the field value.", "enum": [ "Times", "Helvetica", "Courier" ] }, "color": { "type": "string", "description": "Font color of the field value.", "enum": [ "black", "white", "blue" ], "default": "black" }, "background": { "type": "string", "description": "Field box background color.", "enum": [ "black", "white", "blue" ] }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", "enum": [ "left", "center", "right" ], "default": "left" }, "valign": { "type": "string", "description": "Vertical alignment of the field text value.", "enum": [ "top", "center", "bottom" ], "default": "center" }, "format": { "type": "string", "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", "example": "DD/MM/YYYY" }, "mask": { "description": "Set `true` to make sensitive data masked on the document.", "oneOf": [ { "type": "integer" }, { "type": "boolean" } ], "default": false }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } } } } }, "roles": { "type": "array", "description": "A list of roles for the submitter. Use this param to merge multiple roles into one submitter.", "items": { "type": "string" } } } } }, "folder_name": { "type": "string", "example": "Clientes / Acme", "description": "Pasta do envelope (a que a home agrupa). Criada se nao existir; \"Pai / Filha\" cria os dois niveis. Sem este campo o envelope nasce sem pasta. Liste as existentes em GET /folders." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "status", "values", "metadata", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "external_id", "preferences", "role", "embed_src" ], "properties": { "id": { "type": "integer", "description": "Submitter unique ID number." }, "submission_id": { "type": "integer", "description": "Submission UUID." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "nullable": true, "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique key to be used in the signing form URL." }, "status": { "type": "string", "description": "The status of signing request for the submitter.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "values": { "type": "array", "description": "An array of pre-filled values for the submission.", "items": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "Document template field name." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Pre-filled value of the field." } } } }, "metadata": { "type": "object" }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "The name of the submitter." }, "phone": { "type": "string", "nullable": true, "description": "The phone number of the submitter." }, "empresa": { "type": "string", "nullable": true, "description": "Company of the submitter (optional).", "example": "Acme Ltda" }, "cpf": { "type": "string", "nullable": true, "description": "CPF (Brazilian taxpayer ID) of the submitter - digits or formatted. Required to complete the signature; for POST /api/submissions/emails and invited signers it is collected on the signing screen.", "example": "07756352947" }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this submitter within your app." }, "preferences": { "type": "object", "properties": { "send_email": { "type": "boolean", "description": "Indicates whether the signature request email should be sent." }, "send_sms": { "type": "boolean", "description": "Indicates whether the signature request should be sent via SMS." }, "send_whatsapp": { "type": "boolean", "description": "Set `true` to send the signature request via WhatsApp to the submitter's phone number." } } }, "role": { "type": "string", "description": "The role of the submitter in the signing process." }, "embed_src": { "type": "string", "description": "The `src` URL value to embed the signing form or sign via a link." } } } }, "example": [ { "id": 1, "submission_id": 1, "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", "email": "john.doe@example.com", "slug": "pAMimKcyrLjqVt", "sent_at": "2023-12-13T23:04:04.252Z", "opened_at": null, "completed_at": null, "declined_at": null, "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "string", "phone": "+1234567890", "external_id": "2321", "metadata": { "customData": "custom value" }, "status": "sent", "values": [ { "field": "Full Name", "value": "John Doe" } ], "preferences": { "send_email": true, "send_sms": false }, "role": "First Party", "embed_src": "https://app.synexissign.com/s/pAMimKcyrLjqVt" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "422": { "description": "Payload invalido, cota do plano estourada, ou regra de negocio violada. Corpo: {\"status\":422,\"error\":\"\",\"code\":\"\"} — reaja pelo `code` (contrato estavel), nunca por match de string em `error`. Codigo proprio desta porta: `signer.role_unknown` — o `role` de um signatario nao casa com nenhum papel definido no template; a mensagem lista os papeis validos, e NADA e criado (o lote inteiro e recusado). Ate 02/09/2026 esse caso caia num fallback POSICIONAL, que podia vincular o signatario ao papel errado ou descarta-lo, sempre com HTTP 200 — se o seu cliente dependia disso, passe `role` (ou `uuid`) correto. OMITIR o `role` continua valido e resolve por ordem." } } } }, "/submissions/{id}": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Get a submission", "description": "The API endpoint provides the functionality to retrieve information about a submission.", "operationId": "getSubmission", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submission.", "example": 1001 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "source", "submitters_order", "audit_log_url", "combined_document_url", "created_at", "updated_at", "archived_at", "submitters", "created_by_user", "submission_events", "documents", "status", "metadata", "completed_at" ], "properties": { "id": { "type": "integer", "description": "Submission unique ID number." }, "name": { "type": "string", "description": "Name of the document submission", "example": "Test Submission Document" }, "slug": { "type": "string", "description": "Unique slug of the submission." }, "source": { "type": "string", "description": "The source of the submission.", "enum": [ "invite", "bulk", "api", "embed", "link" ] }, "submitters_order": { "type": "string", "description": "The order of submitters.", "enum": [ "random", "preserved" ] }, "audit_log_url": { "type": "string", "nullable": true, "description": "Audit log file URL." }, "combined_document_url": { "type": "string", "nullable": true, "description": "Combined PDF file URL with documents and Audit Log." }, "created_at": { "type": "string", "description": "The date and time when the submission was created." }, "updated_at": { "type": "string", "description": "The date and time when the submission was last updated." }, "archived_at": { "type": "string", "nullable": true, "description": "The date and time when the submission was archived." }, "submitters": { "type": "array", "description": "The list of submitters.", "items": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "external_id", "status", "values", "documents", "role" ], "properties": { "id": { "type": "integer", "description": "Submitter unique ID number." }, "submission_id": { "type": "integer", "description": "Submission unique ID number." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "nullable": true, "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique key to be used in the form signing link and embedded form." }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "Submitter name." }, "phone": { "type": "string", "nullable": true, "description": "Submitter phone number." }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this submitter within your app." }, "status": { "type": "string", "description": "The status of signing request for the submitter.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "values": { "type": "array", "description": "An array of field values for the submitter.", "items": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "Document template field name." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Pre-filled value of the field." } } } }, "documents": { "type": "array", "description": "An array of completed or signed documents by the submitter.", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Document name." }, "url": { "type": "string", "description": "Document URL." } } } }, "role": { "type": "string", "description": "The role of the submitter in the signing process." } } } }, "template": { "type": "object", "required": [ "id", "name", "external_id", "folder_name", "created_at", "updated_at" ], "properties": { "id": { "type": "integer", "description": "Template unique ID number." }, "name": { "type": "string", "description": "The name of the submission template." }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this template within your app." }, "folder_name": { "type": "string", "description": "Folder name where the template is located." }, "created_at": { "type": "string", "description": "The date and time when the submission template was created." }, "updated_at": { "type": "string", "description": "The date and time when the submission template was last updated." } } }, "created_by_user": { "type": "object", "nullable": true, "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the user who created the submission." }, "first_name": { "type": "string", "description": "The first name of the user who created the submission." }, "last_name": { "type": "string", "description": "The last name of the user who created the submission." }, "email": { "type": "string", "description": "The email address of the user who created the submission." } } }, "submission_events": { "type": "array", "items": { "type": "object", "required": [ "id", "submitter_id", "event_type", "event_timestamp" ], "properties": { "id": { "type": "integer", "description": "Submission event unique ID number." }, "submitter_id": { "type": "integer", "description": "Unique identifier of the submitter that triggered the event." }, "event_type": { "type": "string", "description": "Event type.", "enum": [ "send_email", "bounce_email", "complaint_email", "send_reminder_email", "send_sms", "send_2fa_sms", "send_2fa_email", "send_whatsapp", "send_reminder_whatsapp", "send_completed_whatsapp", "send_2fa_whatsapp", "delivered_whatsapp", "read_whatsapp", "failed_whatsapp", "click_whatsapp", "open_email", "click_email", "click_sms", "phone_verified", "email_verified", "start_form", "view_form", "invite_party", "complete_form", "decline_form", "cancel_submission", "delegate_form", "api_complete_form", "create_envelope", "add_party", "blocked_cross_signer_access", "identity_corrected" ] }, "event_timestamp": { "type": "string", "description": "Date and time when the event was triggered." }, "data": { "type": "object", "description": "Additional event details object." } } } }, "documents": { "type": "array", "description": "An array of completed or signed documents of the submission.", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Document name." }, "url": { "type": "string", "description": "Document URL." } } } }, "status": { "type": "string", "description": "The status of the submission. Single ladder: completed > canceled > declined > expired > pending.", "enum": [ "completed", "canceled", "declined", "expired", "pending" ] }, "metadata": { "type": "object", "description": "Object with custom metadata." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submission was fully completed." } } }, "example": { "id": 1, "name": null, "source": "link", "submitters_order": "random", "slug": "VyL4szTwYoSvXq", "audit_log_url": "https://app.synexissign.com/blobs/proxy/hash/example.pdf", "combined_document_url": null, "completed_at": "2023-12-14T15:49:21.701Z", "expire_at": null, "created_at": "2023-12-10T15:48:17.166Z", "updated_at": "2023-12-10T15:49:21.895Z", "archived_at": null, "submitters": [ { "id": 1, "submission_id": 1, "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "email": "submitter@example.com", "slug": "dsEeWrhRD8yDXT", "sent_at": "2023-12-14T15:45:49.011Z", "opened_at": "2023-12-14T15:48:23.011Z", "completed_at": "2023-12-14T15:49:21.701Z", "declined_at": null, "created_at": "2023-12-14T15:48:17.173Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "John Doe", "phone": "+1234567890", "external_id": null, "status": "completed", "metadata": {}, "values": [ { "field": "Full Name", "value": "John Doe" } ], "documents": [ { "name": "example", "url": "https://app.synexissign.com/blobs/proxy/hash/example.pdf" } ], "role": "First Party" } ], "template": { "id": 1, "name": "Example Template", "external_id": "Temp123", "folder_name": "Default", "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z" }, "created_by_user": { "id": 1, "first_name": "Bob", "last_name": "Smith", "email": "bob.smith@example.com" }, "submission_events": [ { "id": 1, "submitter_id": 2, "event_type": "view_form", "event_timestamp": "2023-12-14T15:47:24.566Z", "data": {} } ], "documents": [ { "name": "example", "url": "https://app.synexissign.com/file/hash/example.pdf" } ], "status": "completed" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "delete": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Archive a submission", "description": "The API endpoint allows you to archive a submission.", "operationId": "archiveSubmission", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submission.", "example": 1001 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "archived_at" ], "properties": { "id": { "type": "integer", "description": "Submission unique ID number." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the submission was archived." } } }, "example": { "id": 1, "archived_at": "2023-12-14T15:50:21.799Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Rename or move a submission", "operationId": "updateSubmission", "description": "Renomeia o envelope e/ou o move de pasta — os dois unicos atributos mutaveis depois do envio (expire_at e imutavel). folder_name vazio tira o envelope da pasta; pasta inexistente e criada. Envelope de outra conta responde 403; id inexistente, 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submission.", "example": 1001 } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "example": "Contrato 2026" }, "folder_name": { "type": "string", "example": "Arquivo Morto", "description": "Pasta destino (\"Pai / Filha\" cria a hierarquia). String vazia remove da pasta." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "folder_id": { "type": [ "integer", "null" ] }, "folder": { "type": [ "string", "null" ], "description": "full_name da pasta, ou null" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Envelope inexistente" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submissions/{id}/documents": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Get submission documents", "description": "This endpoint returns a list of partially filled documents for a submission. If the submission has been completed, the final signed documents are returned.", "operationId": "getSubmissionDocuments", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submission.", "example": 1001 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "documents" ], "properties": { "id": { "type": "integer", "description": "Submission unique ID number." }, "documents": { "type": "array", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Document name." }, "url": { "type": "string", "description": "Document URL." } } } } } }, "example": { "id": 1, "documents": [ { "name": "example", "url": "https://app.synexissign.com/file/hash/example.pdf" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submissions/{id}/cancel": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Cancel a submission", "description": "Cancela (anula) um envio: grava `canceled_at`, impede que os signatarios pendentes assinem, avisa por e-mail quem ja tinha recebido o convite e dispara o evento `submission.canceled`.\n\nDIFERENTE de `DELETE /submissions/{id}`, que apenas ARQUIVA: o arquivamento tira o envio da tela do remetente mas mantem o link do signatario valido. Use cancel quando o negocio caiu e o documento nao deve mais ser assinado.\n\nSo funciona enquanto houver signatario pendente e o envio nao estiver ja cancelado, arquivado ou expirado — caso contrario responde 422.", "operationId": "cancelSubmission", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submission.", "example": 1001 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The submission unique identifier.", "example": 1001 }, "canceled_at": { "type": "string", "format": "date-time", "description": "The date and time when the submission was canceled.", "example": "2026-08-05T09:30:00.000Z" } } } } } }, "422": { "description": "O envio nao esta em estado cancelavel (ja cancelado, arquivado, expirado ou sem signatario pendente)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submissions/emails": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Create submissions from emails", "description": "This API endpoint allows you to create submissions for a document template and send them to the specified email addresses. This is a simplified version of the POST /submissions API to be used with Zapier or other automation tools.", "operationId": "createSubmissionsFromEmails", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "template_id", "emails" ], "properties": { "template_id": { "type": "integer", "description": "The unique identifier of the template.", "example": 1000001 }, "emails": { "type": "string", "description": "A comma-separated list of email addresses to send the submission to.", "example": "{{emails}}" }, "send_email": { "type": "boolean", "description": "Set `false` to disable signature request emails sending.", "default": true }, "message": { "type": "object", "properties": { "subject": { "type": "string", "description": "Custom signature request email subject." }, "body": { "type": "string", "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "status", "values", "metadata", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "external_id", "preferences", "role", "embed_src" ], "properties": { "id": { "type": "integer", "description": "Submitter unique ID number." }, "submission_id": { "type": "integer", "description": "Submission UUID." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "nullable": true, "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique key to be used in the signing form URL." }, "status": { "type": "string", "description": "The status of signing request for the submitter.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "values": { "type": "array", "description": "An array of pre-filled values for the submission.", "items": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "Document template field name." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Pre-filled value of the field." } } } }, "metadata": { "type": "object" }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "The name of the submitter." }, "phone": { "type": "string", "nullable": true, "description": "The phone number of the submitter." }, "empresa": { "type": "string", "nullable": true, "description": "Company of the submitter (optional).", "example": "Acme Ltda" }, "cpf": { "type": "string", "nullable": true, "description": "CPF (Brazilian taxpayer ID) of the submitter - digits or formatted. Required to complete the signature; for POST /api/submissions/emails and invited signers it is collected on the signing screen.", "example": "07756352947" }, "external_id": { "type": "string", "nullable": true, "description": "Your application-specific unique string key to identify this submitter within your app." }, "preferences": { "type": "object", "properties": { "send_email": { "type": "boolean", "description": "Indicates whether the signature request email should be sent." }, "send_sms": { "type": "boolean", "description": "Indicates whether the signature request should be sent via SMS." }, "send_whatsapp": { "type": "boolean", "description": "Set `true` to send the signature request via WhatsApp to the submitter's phone number." } } }, "role": { "type": "string", "description": "The role of the submitter in the signing process." }, "embed_src": { "type": "string", "description": "The `src` URL value to embed the signing form or sign via a link." } } } }, "example": [ { "id": 1, "submission_id": 1, "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", "email": "john.doe@example.com", "slug": "pAMimKcyrLjqVt", "sent_at": "2023-12-13T23:04:04.252Z", "opened_at": null, "completed_at": null, "declined_at": null, "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "string", "phone": "+1234567890", "external_id": "2321", "metadata": { "customData": "custom value" }, "status": "sent", "values": [ { "field": "Full Name", "value": "John Doe" } ], "preferences": { "send_email": true, "send_sms": false }, "role": "First Party", "embed_src": "https://app.synexissign.com/s/pAMimKcyrLjqVt" }, { "id": 2, "submission_id": 1, "uuid": "884d545b-3396-49f1-8c07-05b8b2a78755", "email": "alan.smith@example.com", "slug": "SEwc65vHNDH3QS", "sent_at": "2023-12-13T23:04:04.252Z", "opened_at": null, "completed_at": null, "declined_at": null, "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "string", "phone": "+1234567890", "external_id": "2321", "metadata": { "customData": "custom value" }, "status": "sent", "values": [ { "field": "Full Name", "value": "Roe Moe" } ], "preferences": { "send_email": true, "send_sms": false }, "role": "First Party", "embed_src": "SEwc65vHNDH3QS" } ] } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submitters/{id}": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Submitters" ], "summary": "Get a submitter", "description": "The API endpoint provides functionality to retrieve information about a submitter, along with the submitter documents and field values.", "operationId": "getSubmitter", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submitter.", "example": 500001 } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "status", "external_id", "metadata", "preferences", "template", "submission_events", "values", "documents", "role" ], "properties": { "id": { "type": "integer", "description": "Submitter unique ID number." }, "submission_id": { "type": "integer", "description": "Submission unique ID number." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "nullable": true, "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique key to be used in the form signing link and embedded form." }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "Submitter name." }, "phone": { "type": "string", "nullable": true, "description": "Submitter phone number." }, "status": { "type": "string", "description": "Submitter's submission status.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "external_id": { "type": "string", "nullable": true, "description": "The unique applications-specific identifier" }, "metadata": { "type": "object", "description": "Metadata object with additional submitter information." }, "preferences": { "type": "object", "description": "Submitter preferences." }, "template": { "type": "object", "required": [ "id", "name", "created_at", "updated_at" ], "description": "Base template details.", "properties": { "id": { "type": "number", "description": "The template's unique identifier." }, "name": { "type": "string", "description": "The template's name." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "submission_events": { "type": "array", "items": { "type": "object", "required": [ "id", "submitter_id", "event_type", "event_timestamp" ], "properties": { "id": { "type": "integer", "description": "Submission event unique ID number." }, "submitter_id": { "type": "integer", "description": "Unique identifier of the submitter that triggered the event." }, "event_type": { "type": "string", "description": "Event type.", "enum": [ "send_email", "bounce_email", "complaint_email", "send_reminder_email", "send_sms", "send_2fa_sms", "send_2fa_email", "send_whatsapp", "send_reminder_whatsapp", "send_completed_whatsapp", "send_2fa_whatsapp", "delivered_whatsapp", "read_whatsapp", "failed_whatsapp", "click_whatsapp", "open_email", "click_email", "click_sms", "phone_verified", "email_verified", "start_form", "view_form", "invite_party", "complete_form", "decline_form", "cancel_submission", "delegate_form", "api_complete_form", "create_envelope", "add_party", "blocked_cross_signer_access", "identity_corrected" ] }, "event_timestamp": { "type": "string", "description": "Date and time when the event was triggered." }, "data": { "type": "object", "description": "Additional event details object." } } } }, "values": { "type": "array", "description": "An array of pre-filled values for the submitter.", "items": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "Document template field name." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Pre-filled value of the field." } } } }, "documents": { "type": "array", "description": "An array of completed or signed documents by the submitter.", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Document name." }, "url": { "type": "string", "description": "Document URL." } } } }, "role": { "type": "string", "description": "The role of the submitter in the signing process." } } }, "example": { "id": 7, "submission_id": 3, "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "email": "submitter@example.com", "slug": "dsEeWrhRD8yDXT", "sent_at": "2023-12-14T15:45:49.011Z", "opened_at": "2023-12-14T15:48:23.011Z", "completed_at": "2023-12-10T15:49:21.701Z", "declined_at": null, "created_at": "2023-12-14T15:48:17.173Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "John Doe", "phone": "+1234567890", "status": "completed", "external_id": null, "metadata": {}, "preferences": {}, "template": { "id": 2, "name": "Example Template", "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z" }, "submission_events": [ { "id": 12, "submitter_id": 7, "event_type": "view_form", "event_timestamp": "2023-12-14T15:47:17.351Z", "data": {} } ], "values": [ { "field": "Full Name", "value": "John Doe" } ], "documents": [ { "name": "sample-document", "url": "https://app.synexissign.com/file/hash/sample-document.pdf" } ], "role": "First Party" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "put": { "security": [ { "AuthToken": [] } ], "tags": [ "Submitters" ], "summary": "Update a submitter", "description": "The API endpoint allows you to update submitter details, pre-fill or update field values and re-send emails.
Related Guides
Automatically sign documents via API\n\nCom `Idempotency-Key`: o replay devolve a resposta memorizada e NAO redispara convite (send_email/send_sms). Para reenviar de proposito, use uma chave NOVA a cada tentativa — repetir a chave transforma o reenvio em replay silencioso (200 sem e-mail, marcado so pelo header Idempotent-Replay).\n\n`send_whatsapp: true` dispara o convite por WhatsApp (exige telefone, canal ativo e plano com a feature). O e-mail co-dispara como no `send_sms`, salvo enviado ha pouco (valvula anti-rajada) ou `send_email: false` explicito no mesmo request — que tambem fica gravado como preferencia do signatario.", "operationId": "updateSubmitter", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submitter.", "example": 500001 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the submitter." }, "email": { "type": "string", "description": "The email address of the submitter.", "format": "email", "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "The phone number of the submitter, formatted according to the E.164 standard.", "example": "+1234567890" }, "phone_country": { "type": "string", "enum": [ "BR" ], "description": "Converte um numero NACIONAL para E.164 usando o DDI do pais indicado (ex.: 'BR'). So converte com o pedido explicito — a API nunca infere DDI; numero ja internacional ('+...') passa intacto. Para BR: o 0 de tronco inicial e descartado e o numero deve ter 10-11 digitos (fora disso, 422 — inclusive numero que ja embute o 55 sem '+'). Sem este campo, telefone sem '+' e 422." }, "empresa": { "type": "string", "description": "Company of the submitter (optional).", "example": "Acme Ltda" }, "cpf": { "type": "string", "description": "CPF (Brazilian taxpayer ID) of the submitter - digits or formatted. Required to complete the signature; for POST /api/submissions/emails and invited signers it is collected on the signing screen.", "example": "07756352947" }, "values": { "type": "object", "description": "An object with pre-filled values for the submission. Use field names for keys of the object. For more configurations see `fields` param." }, "external_id": { "type": "string", "description": "Your application-specific unique string key to identify this submitter within your app." }, "send_email": { "type": "boolean", "description": "Set `true` to re-send signature request emails. Silently suppressed (200 without sending) when this submitter was emailed within the last 10 hours — reminder emails and queued invitations count. A changed email address bypasses the window. For a 422-with-reason contract, use `POST /submitters/{id}/send_email` instead." }, "send_sms": { "type": "boolean", "description": "Set `true` to re-send signature request via phone number SMS.", "default": false }, "send_whatsapp": { "type": "boolean", "description": "Set `true` to send the signature request via WhatsApp to the submitter's phone number. Requires a phone, WhatsApp opt-in, the WhatsApp feature on the plan and the channel enabled. Silently suppressed (200 without sending) when this submitter was messaged on WhatsApp within the last 10 hours — the window is PER CHANNEL, so a recent email does not suppress WhatsApp (and vice versa). Note: unless `send_email: false` is passed, the invitation email is co-dispatched for submitters with email. For a 422-with-reason contract, use `POST /submitters/{id}/send_whatsapp` instead.", "default": false }, "reply_to": { "type": "string", "description": "Specify Reply-To address to use in the notification emails." }, "completed": { "type": "boolean", "description": "Pass `true` to mark submitter as completed and auto-signed via API." }, "metadata": { "type": "object", "description": "Metadata object with additional submitter information.", "example": "{ \"customField\": \"value\" }" }, "completed_redirect_url": { "type": "string", "description": "Submitter specific URL to redirect to after the submission completion." }, "require_phone_2fa": { "type": "boolean", "description": "Set to `true` to require phone 2FA verification via a one-time code sent to the phone number in order to access the documents.", "default": false }, "message": { "type": "object", "properties": { "subject": { "type": "string", "description": "Custom signature request email subject." }, "body": { "type": "string", "description": "Custom signature request email body. Can include the following variables: {{template.name}}, {{submitter.link}}, {{account.name}}." } } }, "fields": { "type": "array", "description": "A list of configurations for template document form fields.", "items": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Document template field name.", "example": "First Name" }, "default_value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Default value of the field. Use base64 encoded file or a public URL to the image file to set default signature or image fields.", "example": "Acme" }, "readonly": { "type": "boolean", "description": "Set `true` to make it impossible for the submitter to edit predefined field value.", "default": false }, "required": { "type": "boolean", "description": "Set `true` to make the field required." }, "validation": { "type": "object", "properties": { "pattern": { "type": "string", "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", "example": "[A-Z]{4}" }, "message": { "type": "string", "description": "A custom error message to display on validation failure." }, "min": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Minimum allowed number value or date depending on field type." }, "max": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Maximum allowed number value or date depending on field type." }, "step": { "type": "number", "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." } } }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels.", "example": 12 }, "font_type": { "type": "string", "description": "Font type of the field value.", "enum": [ "bold", "italic", "bold_italic" ] }, "font": { "type": "string", "description": "Font family of the field value.", "enum": [ "Times", "Helvetica", "Courier" ] }, "color": { "type": "string", "description": "Font color of the field value.", "enum": [ "black", "white", "blue" ], "default": "black" }, "background": { "type": "string", "description": "Field box background color.", "enum": [ "black", "white", "blue" ] }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", "enum": [ "left", "center", "right" ], "default": "left" }, "valign": { "type": "string", "description": "Vertical alignment of the field text value.", "enum": [ "top", "center", "bottom" ], "default": "center" }, "format": { "type": "string", "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", "example": "DD/MM/YYYY" }, "mask": { "description": "Set `true` to make sensitive data masked on the document.", "oneOf": [ { "type": "integer" }, { "type": "boolean" } ], "default": false }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "status", "external_id", "metadata", "preferences", "values", "documents", "role", "embed_src" ], "properties": { "id": { "type": "integer", "description": "Submitter unique ID number." }, "submission_id": { "type": "integer", "description": "Submission unique ID number." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "nullable": true, "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique key to be used in the form signing link and embedded form." }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "Submitter name." }, "phone": { "type": "string", "nullable": true, "description": "Submitter phone number." }, "status": { "type": "string", "description": "Submitter's submission status.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "external_id": { "type": "string", "nullable": true, "description": "The unique applications-specific identifier" }, "metadata": { "type": "object", "description": "Metadata object with additional submitter information." }, "preferences": { "type": "object", "description": "Submitter preferences." }, "values": { "type": "array", "description": "An array of pre-filled values for the submitter.", "items": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "Document template field name." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Pre-filled value of the field." } } } }, "documents": { "type": "array", "description": "An array of completed or signed documents by the submitter.", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Document name." }, "url": { "type": "string", "description": "Document URL." } } } }, "role": { "type": "string", "description": "The role of the submitter in the signing process." }, "embed_src": { "type": "string", "description": "The `src` URL value to embed the signing form or sign via a link." } } }, "example": { "id": 1, "submission_id": 12, "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "email": "submitter@example.com", "slug": "dsEeWrhRD8yDXT", "sent_at": "2023-12-14T15:45:49.011Z", "opened_at": "2023-12-14T15:48:23.011Z", "completed_at": "2023-12-10T15:49:21.701Z", "declined_at": null, "created_at": "2023-12-14T15:48:17.173Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "John Doe", "phone": "+1234567890", "status": "completed", "external_id": null, "metadata": {}, "preferences": {}, "values": [ { "field": "Full Name", "value": "John Doe" } ], "documents": [], "role": "First Party", "embed_src": "https://app.synexissign.com/s/pAMimKcyrLjqVt" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submitters/{id}/send_email": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submitters" ], "summary": "Resend the signature request email", "description": "Reenvia o convite de assinatura para UM signatario — util para cobrar a assinatura que esta faltando sem tocar nos demais signatarios do envio.\n\nGranularidade por signatario de proposito: nenhum outro signatario do mesmo envio recebe e-mail.\n\nTeto de 10 horas por signatario (lembrete automatico e convite ainda na fila contam; chamadas em rajada sao serializadas — a segunda ja recebe 422). Tambem responde 422, sem enviar nada, quando reenviar nao faria sentido: envio cancelado, arquivado ou expirado; template arquivado; envio recusado por qualquer signatario; signatario que ja assinou, sem e-mail ou com e-mail invalido; signatario ainda fora da vez no fluxo sequencial; ou instancia self-host sem envio de e-mail configurado. A mensagem em `error` diz qual caso ocorreu.\n\nCom `Idempotency-Key`: cada tentativa intencional de reenvio exige uma chave NOVA — a mesma chave devolve o replay memorizado sem disparar e-mail nenhum.", "operationId": "resendSubmitterEmail", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submitter.", "example": 500001 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The submitter unique identifier.", "example": 500001 }, "email": { "type": "string", "description": "The email address the invitation was sent to.", "example": "john.doe@example.com" }, "sent_at": { "type": "string", "format": "date-time", "description": "The date and time when the invitation was FIRST sent to this submitter. A resend does not move this timestamp — use the `send_email` submitter events to audit each delivery.", "example": "2026-08-11T09:30:00.000Z" } } } } } }, "422": { "description": "O convite nao pode ser reenviado: ja enviado (ou lembrete/reserva de reenvio) nas ultimas 10 horas, envio cancelado, arquivado ou expirado, template arquivado, envio recusado por outro signatario, signatario que ja assinou, que recusou, sem e-mail ou com e-mail invalido, ainda fora da vez no fluxo sequencial, ou conta sem envio de e-mail configurado (self-host). Cada caso tem um `code` proprio no corpo: envelope.canceled, envelope.archived, envelope.expired, envelope.declined, template.archived, signer.already_completed, signer.already_declined, signer.no_email, signer.invalid_email, signer.awaiting_turn, account.emails_disabled e signer.sent_recently (aguarde a janela de 10h antes de re-tentar)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submitters/{id}/send_whatsapp": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submitters" ], "summary": "Resend the signature request via WhatsApp", "description": "Reenvia o convite de assinatura de UM signatario pelo canal WHATSAPP — a irma do `POST /submitters/{id}/send_email`, com a mesma granularidade por signatario.\n\nExige signatario com telefone e opt-in de WhatsApp (`send_whatsapp` na criacao, no PUT ou no painel), plano com a feature de WhatsApp e o canal habilitado na plataforma.\n\nTeto de 10 horas POR CANAL e por signatario (entrega, lembrete automatico por WhatsApp e convite ainda na fila contam; um e-mail recente NAO conta — cobrar por WhatsApp depois do e-mail e o caso de uso). Responde 422 com `code` proprio quando reenviar nao faria sentido, sem enviar nada.\n\nO `sent_at` do corpo e o timestamp ATUAL e pode ser null: no canal WhatsApp ele nasce na ENTREGA da mensagem — 200 aqui significa \"convite enfileirado e reservado\", nao \"entregue\". Acompanhe a entrega pelos eventos `send_whatsapp`/`failed_whatsapp` do signatario.\n\nCom `Idempotency-Key`: cada tentativa intencional de reenvio exige uma chave NOVA — a mesma chave devolve o replay memorizado sem disparar mensagem nenhuma.", "operationId": "resendSubmitterWhatsapp", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submitter.", "example": 500001 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "successful operation", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The submitter unique identifier.", "example": 500001 }, "phone": { "type": "string", "description": "The phone number the invitation was sent to (E.164).", "example": "+5511999998888" }, "sent_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When the FIRST invitation reached this submitter on any channel. Null until a delivery happens — on WhatsApp this is stamped at DELIVERY, not at enqueue.", "example": "2026-08-24T09:30:00.000Z" } } } } } }, "422": { "description": "O convite nao pode ser reenviado por WhatsApp: ja cobrado pelo canal nas ultimas 10 horas, envio cancelado, arquivado ou expirado, template arquivado, envio recusado por outro signatario, signatario que ja assinou, que recusou, sem telefone, sem opt-in de WhatsApp, ainda fora da vez no fluxo sequencial, plano sem a feature ou canal desabilitado. Cada caso tem um `code` proprio no corpo: envelope.canceled, envelope.archived, envelope.expired, envelope.declined, template.archived, signer.already_completed, signer.already_declined, signer.no_phone, signer.whatsapp_not_opted_in, signer.awaiting_turn, account.plan_without_whatsapp, account.whatsapp_disabled e signer.sent_recently (aguarde a janela de 10h do canal antes de re-tentar)." }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submitters": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Submitters" ], "summary": "List all submitters", "description": "The API endpoint provides the ability to retrieve a list of submitters.", "operationId": "getSubmitters", "parameters": [ { "name": "submission_id", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The submission ID allows you to receive only the submitters related to that specific submission." }, { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submitters on name, email or phone partial match." }, { "name": "slug", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Filter submitters by unique slug.", "example": "zAyL9fH36Havvm" }, { "name": "completed_after", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-03-05 9:32:20", "description": "The date and time string value to filter submitters that completed the submission after the specified date and time." }, { "name": "completed_before", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2024-03-06 19:32:20", "description": "The date and time string value to filter submitters that completed the submission before the specified date and time." }, { "name": "external_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The unique applications-specific identifier provided for a submitter when initializing a signature request. It allows you to receive only submitters with a specified external id." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The number of submitters to return. Default value is 10. Maximum value is 100." }, { "name": "after", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the submitter to start the list from. It allows you to receive only submitters with id greater than the specified value. Pass ID value from the `pagination.next` response to load the next batch of submitters." }, { "name": "before", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "The unique identifier of the submitter to end the list with. It allows you to receive only submitters with id less than the specified value." } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "required": [ "id", "submission_id", "uuid", "email", "slug", "sent_at", "opened_at", "completed_at", "declined_at", "created_at", "updated_at", "name", "phone", "status", "external_id", "preferences", "metadata", "submission_events", "values", "documents", "role" ], "properties": { "id": { "type": "integer", "description": "Submitter unique ID number." }, "submission_id": { "type": "integer", "description": "Submission unique ID number." }, "uuid": { "type": "string", "description": "Submitter UUID." }, "email": { "type": "string", "description": "The email address of the submitter." }, "slug": { "type": "string", "description": "Unique slug of the submitter form." }, "sent_at": { "type": "string", "nullable": true, "description": "The date and time when the signing request was sent to the submitter." }, "opened_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter opened the signing form." }, "completed_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter completed the signing form." }, "declined_at": { "type": "string", "nullable": true, "description": "The date and time when the submitter declined the signing form." }, "created_at": { "type": "string", "description": "The date and time when the submitter was created." }, "updated_at": { "type": "string", "description": "The date and time when the submitter was last updated." }, "name": { "type": "string", "nullable": true, "description": "Submitter name." }, "phone": { "type": "string", "nullable": true, "description": "Submitter phone number." }, "status": { "type": "string", "description": "Submitter's submission status.", "enum": [ "completed", "declined", "opened", "sent", "awaiting" ] }, "external_id": { "type": "string", "nullable": true, "description": "The unique applications-specific identifier" }, "preferences": { "type": "object", "description": "Submitter preferences." }, "metadata": { "type": "object", "description": "Metadata object with additional submitter information." }, "submission_events": { "type": "array", "items": { "type": "object", "required": [ "id", "submitter_id", "event_type", "event_timestamp" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the submission event." }, "submitter_id": { "type": "integer", "description": "Unique identifier of the submitter that triggered the event." }, "event_type": { "type": "string", "description": "Event type.", "enum": [ "send_email", "bounce_email", "complaint_email", "send_reminder_email", "send_sms", "send_2fa_sms", "send_2fa_email", "send_whatsapp", "send_reminder_whatsapp", "send_completed_whatsapp", "send_2fa_whatsapp", "delivered_whatsapp", "read_whatsapp", "failed_whatsapp", "click_whatsapp", "open_email", "click_email", "click_sms", "phone_verified", "email_verified", "start_form", "view_form", "invite_party", "complete_form", "decline_form", "cancel_submission", "delegate_form", "api_complete_form", "create_envelope", "add_party", "blocked_cross_signer_access", "identity_corrected" ] }, "event_timestamp": { "type": "string", "description": "Date and time when the event was triggered." }, "data": { "type": "object", "description": "Additional event details object." } } } }, "values": { "type": "array", "description": "An array of pre-filled values for the submission.", "items": { "type": "object", "required": [ "field", "value" ], "properties": { "field": { "type": "string", "description": "Document template field name." }, "value": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } ], "description": "Pre-filled value of the field." } } } }, "documents": { "type": "array", "description": "An array of completed or signed documents by the submitter.", "items": { "type": "object", "required": [ "name", "url" ], "properties": { "name": { "type": "string", "description": "Document name." }, "url": { "type": "string", "description": "Document URL." } } } }, "role": { "type": "string", "description": "The role of the submitter in the signing process." } } } }, "pagination": { "type": "object", "required": [ "count", "next", "prev" ], "properties": { "count": { "type": "integer", "description": "Submitters count." }, "next": { "type": "integer", "nullable": true, "description": "The ID of the submitter after which the next page starts." }, "prev": { "type": "integer", "nullable": true, "description": "The ID of the submitter before which the previous page ends." } } } } }, "example": { "data": [ { "id": 7, "submission_id": 3, "uuid": "0954d146-db8c-4772-aafe-2effc7c0e0c0", "email": "submitter@example.com", "slug": "dsEeWrhRD8yDXT", "sent_at": "2023-12-14T15:45:49.011Z", "opened_at": "2023-12-14T15:48:23.011Z", "completed_at": "2023-12-14T15:49:21.701Z", "declined_at": null, "created_at": "2023-12-14T15:48:17.173Z", "updated_at": "2023-12-14T15:50:21.799Z", "name": "John Doe", "phone": "+1234567890", "status": "completed", "external_id": null, "preferences": {}, "metadata": {}, "template": { "id": 2, "name": "Example Template", "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z" }, "submission_events": [ { "id": 12, "submitter_id": 7, "event_type": "view_form", "event_timestamp": "2023-12-14T15:48:17.351Z", "data": {} } ], "values": [ { "field": "Full Name", "value": "John Doe" } ], "documents": [ { "name": "sample-document", "url": "https://app.synexissign.com/file/eyJfcmFpbHMiOnsiIiwiZXhwIjpudWxsLCJwdXIiOiJibG9iX2lkIn19--f9758362acced0f3c86cdffad02800e/sample-document.pdf" } ], "role": "First Party" } ], "pagination": { "count": 1, "next": 1, "prev": 1 } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/{id}/clone": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Clone a template", "description": "The API endpoint allows you to clone existing template into a new template.", "operationId": "cloneTemplate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the documents template.", "example": 1000001 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Template name. Existing name with (Clone) suffix will be used if not specified.", "example": "Cloned Template" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be cloned." }, "external_id": { "type": "string", "description": "Your application-specific unique string key to identify this template within your app." } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "preferences", "schema", "fields", "submitters", "author_id", "archived_at", "created_at", "updated_at", "source", "external_id", "folder_id", "folder_name", "author", "documents" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document template." }, "slug": { "type": "string", "description": "Unique slug of the document template." }, "name": { "type": "string", "description": "Name of the template." }, "preferences": { "type": "object", "description": "Template preferences." }, "schema": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "attachment_uuid", "name" ], "properties": { "attachment_uuid": { "type": "string", "description": "Unique indentifier of attached document to the template." }, "name": { "type": "string", "description": "Name of the attached document to the template." } } } }, "fields": { "type": "array", "description": "List of fields to be filled in the template.", "items": { "type": "object", "required": [ "uuid", "submitter_uuid", "name", "type", "required", "areas" ], "properties": { "uuid": { "type": "string", "description": "Unique identifier of the field." }, "submitter_uuid": { "type": "string", "description": "Unique identifier of the submitter that filled the field." }, "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels." }, "font_type": { "type": "string", "description": "Font type of the field value." }, "font": { "type": "string", "description": "Font family of the field value." }, "color": { "type": "string", "description": "Font color of the field value." }, "background": { "type": "string", "description": "Field box background color." }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." }, "valign": { "type": "string", "description": "Vertical alignment of the field text value." }, "format": { "type": "string", "description": "The data format for different field types." }, "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } }, "areas": { "type": "array", "description": "List of areas where the field is located in the document.", "items": { "type": "object", "required": [ "x", "y", "w", "h", "attachment_uuid", "page" ], "properties": { "x": { "type": "number", "description": "X coordinate of the area where the field is located in the document." }, "y": { "type": "number", "description": "Y coordinate of the area where the field is located in the document." }, "w": { "type": "number", "description": "Width of the area where the field is located in the document." }, "h": { "type": "number", "description": "Height of the area where the field is located in the document." }, "attachment_uuid": { "type": "string", "description": "Unique identifier of the attached document where the field is located." }, "page": { "type": "integer", "description": "Page number of the attached document where the field is located." } } } } } } }, "submitters": { "type": "array", "items": { "type": "object", "required": [ "name", "uuid" ], "properties": { "name": { "type": "string", "description": "Submitter name." }, "uuid": { "type": "string", "description": "Unique identifier of the submitter." } } } }, "author_id": { "type": "integer", "description": "Unique identifier of the author of the template." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the template was archived." }, "created_at": { "type": "string", "description": "Date and time when the template was created." }, "updated_at": { "type": "string", "description": "Date and time when the template was updated." }, "source": { "type": "string", "description": "Source of the template.", "enum": [ "native", "api", "embed" ] }, "external_id": { "type": "string", "nullable": true, "description": "Identifier of the template in the external system." }, "folder_id": { "type": "integer", "description": "Unique identifier of the folder where the template is placed." }, "folder_name": { "type": "string", "description": "Folder name where the template is placed." }, "author": { "type": "object", "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the author." }, "first_name": { "type": "string", "description": "First name of the author." }, "last_name": { "type": "string", "description": "Last name of the author." }, "email": { "type": "string", "description": "Author email." } } }, "documents": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "id", "uuid", "url", "preview_image_url", "filename" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document." }, "uuid": { "type": "string", "description": "Unique identifier of the document." }, "url": { "type": "string", "description": "URL of the document." }, "preview_image_url": { "type": "string", "description": "Document preview image URL." }, "filename": { "type": "string", "description": "Document filename." } } } } } }, "example": { "id": 6, "slug": "Xc7opTqwwV9P7x", "name": "Cloned Template", "schema": [ { "attachment_uuid": "68aa0716-61f0-4535-9ba4-6c00f835b080", "name": "sample-document" } ], "fields": [ { "uuid": "93c7065b-1b19-4551-b67b-9946bf1c11c9", "submitter_uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5", "name": "Name", "type": "text", "required": true, "areas": [ { "page": 0, "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", "x": 0.403158189124654, "y": 0.04211750189825361, "w": 0.100684625476058, "h": 0.01423690205011389 } ] } ], "submitters": [ { "name": "First Party", "uuid": "ad128012-756d-4d17-b728-6f6b1d482bb5" } ], "author_id": 1, "archived_at": null, "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z", "source": "api", "folder_id": 2, "folder_name": "Default", "external_id": null, "author": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, "documents": [ { "id": 9, "uuid": "ded62277-9705-4fac-b5dc-58325d4102eb", "url": "https://app.synexissign.com/file/hash/sample-document.pdf", "filename": "sample-document.pdf" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/html": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Create a template from HTML", "description": "Cria um template de documento a partir de HTML, renderizado em PDF no servidor via Gotenberg/Chromium — requer `GOTENBERG_URL` configurado (sem o conversor o endpoint responde 422). Suporta tags de campo como `` (text, signature, initials, date, checkbox, image, file, phone, number, select, radio, stamp), alem de `html_header`/`html_footer` e `size` (Letter por padrao). Suporta upsert por `external_id`.", "operationId": "createTemplateFromHtml", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "HTML template with field tags.", "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" }, "html_header": { "type": "string", "description": "HTML template of the header to be displayed on every page." }, "html_footer": { "type": "string", "description": "HTML template of the footer to be displayed on every page." }, "name": { "type": "string", "description": "Template name. Random uuid will be assigned when not specified.", "example": "Test Template" }, "size": { "type": "string", "default": "Letter", "description": "Page size. Letter 8.5 x 11 will be assigned when not specified.", "enum": [ "Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A4", "A5", "A6" ], "example": "A4" }, "external_id": { "type": "string", "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new HTML.", "example": "714d974e-83d8-11ee-b962-0242ac120002" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, "documents": { "type": "array", "description": "The list of documents built from HTML. Can be used to create a template with multiple documents. Leave `documents` param empty when using a top-level `html` param for a template with a single document.", "items": { "type": "object", "required": [ "html" ], "properties": { "html": { "type": "string", "description": "HTML template with field tags.", "example": "

Lorem Ipsum is simply dummy text of the\n\n\nand typesetting industry

\n" }, "name": { "type": "string", "description": "Document name. Random uuid will be assigned when not specified.", "example": "Test Document" } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "preferences", "schema", "fields", "submitters", "author_id", "archived_at", "created_at", "updated_at", "source", "external_id", "folder_id", "folder_name", "author", "documents" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document template." }, "slug": { "type": "string", "description": "Unique slug of the document template." }, "name": { "type": "string", "description": "Name of the template." }, "preferences": { "type": "object", "description": "Template preferences." }, "schema": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "attachment_uuid", "name" ], "properties": { "attachment_uuid": { "type": "string", "description": "Unique indentifier of attached document to the template." }, "name": { "type": "string", "description": "Name of the attached document to the template." } } } }, "fields": { "type": "array", "description": "List of fields to be filled in the template.", "items": { "type": "object", "required": [ "uuid", "submitter_uuid", "name", "type", "required", "areas" ], "properties": { "uuid": { "type": "string", "description": "Unique identifier of the field." }, "submitter_uuid": { "type": "string", "description": "Unique identifier of the submitter that filled the field." }, "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels." }, "font_type": { "type": "string", "description": "Font type of the field value." }, "font": { "type": "string", "description": "Font family of the field value." }, "color": { "type": "string", "description": "Font color of the field value." }, "background": { "type": "string", "description": "Field box background color." }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." }, "valign": { "type": "string", "description": "Vertical alignment of the field text value." }, "format": { "type": "string", "description": "The data format for different field types." }, "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } }, "areas": { "type": "array", "description": "List of areas where the field is located in the document.", "items": { "type": "object", "required": [ "x", "y", "w", "h", "attachment_uuid", "page" ], "properties": { "x": { "type": "number", "description": "X coordinate of the area where the field is located in the document." }, "y": { "type": "number", "description": "Y coordinate of the area where the field is located in the document." }, "w": { "type": "number", "description": "Width of the area where the field is located in the document." }, "h": { "type": "number", "description": "Height of the area where the field is located in the document." }, "attachment_uuid": { "type": "string", "description": "Unique identifier of the attached document where the field is located." }, "page": { "type": "integer", "description": "Page number of the attached document where the field is located." } } } } } } }, "submitters": { "type": "array", "items": { "type": "object", "required": [ "name", "uuid" ], "properties": { "name": { "type": "string", "description": "Submitter name." }, "uuid": { "type": "string", "description": "Unique identifier of the submitter." } } } }, "author_id": { "type": "integer", "description": "Unique identifier of the author of the template." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the template was archived." }, "created_at": { "type": "string", "description": "Date and time when the template was created." }, "updated_at": { "type": "string", "description": "Date and time when the template was updated." }, "source": { "type": "string", "description": "Source of the template.", "enum": [ "native", "api", "embed" ] }, "external_id": { "type": "string", "nullable": true, "description": "Identifier of the template in the external system." }, "folder_id": { "type": "integer", "description": "Unique identifier of the folder where the template is placed." }, "folder_name": { "type": "string", "description": "Folder name where the template is placed." }, "author": { "type": "object", "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the author." }, "first_name": { "type": "string", "description": "First name of the author." }, "last_name": { "type": "string", "description": "Last name of the author." }, "email": { "type": "string", "description": "Author email." } } }, "documents": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "id", "uuid", "url", "preview_image_url", "filename" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document." }, "uuid": { "type": "string", "description": "Unique identifier of the document." }, "url": { "type": "string", "description": "URL of the document." }, "preview_image_url": { "type": "string", "description": "Document preview image URL." }, "filename": { "type": "string", "description": "Document filename." } } } } } }, "example": { "id": 3, "slug": "ZQpF222rFBv71q", "name": "Demo Template", "schema": [ { "name": "Demo Template", "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5" } ], "fields": [ { "name": "Name", "required": false, "type": "text", "uuid": "a06c49f6-4b20-4442-ac7f-c1040d2cf1ac", "submitter_uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3", "areas": [ { "page": 0, "attachment_uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", "x": 0.403158189124654, "y": 0.04211750189825361, "w": 0.100684625476058, "h": 0.01423690205011389 } ] } ], "submitters": [ { "name": "Submitter", "uuid": "93ba628c-5913-4456-a1e9-1a81ad7444b3" } ], "author_id": 1, "archived_at": null, "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z", "source": "api", "folder_id": 1, "folder_name": "Default", "external_id": "f0b4714f-e44b-4993-905b-68b4451eef8c", "author": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, "documents": [ { "id": 3, "uuid": "09a8bc73-a7a9-4fd9-8173-95752bdf0af5", "url": "https://app.synexissign.com/file/hash/Test%20Template.pdf" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/docx": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Create a template from Word DOCX", "description": "Cria um template de documento a partir de um DOCX (base64 ou URL), convertido para PDF no servidor via Gotenberg/LibreOffice — requer `GOTENBERG_URL` configurado (sem o conversor o endpoint responde 422). Form fields do DOCX sao preservados como AcroForm e viram campos do template. Suporta upsert por `external_id`.", "operationId": "createTemplateFromDocx", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "name": { "type": "string", "description": "Name of the template", "example": "Test DOCX" }, "external_id": { "type": "string", "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new document.", "example": "unique-key" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, "documents": { "type": "array", "items": { "type": "object", "required": [ "name", "file" ], "properties": { "name": { "type": "string", "description": "Name of the document." }, "file": { "type": "string", "example": "base64", "format": "base64", "description": "Base64-encoded content of the DOCX file or downloadable file URL" }, "fields": { "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the field." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "role": { "type": "string", "description": "Role name of the signer." }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "title": { "type": "string", "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." }, "description": { "type": "string", "description": "Field description displayed on the signing form. Supports Markdown." }, "areas": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "number", "description": "X-coordinate of the field area." }, "y": { "type": "number", "description": "Y-coordinate of the field area." }, "w": { "type": "number", "description": "Width of the field area." }, "h": { "type": "number", "description": "Height of the field area." }, "page": { "type": "integer", "description": "Page number of the field area. Starts from 1." }, "option": { "type": "string", "description": "Option string value for 'radio' and 'multiple' select field types." } } } }, "options": { "type": "array", "description": "An array of option values for 'select' field type.", "items": { "type": "string" }, "example": [ "Option A", "Option B" ] }, "validation": { "type": "object", "properties": { "pattern": { "type": "string", "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", "example": "[A-Z]{4}" }, "message": { "type": "string", "description": "A custom error message to display on validation failure." }, "min": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Minimum allowed number value or date depending on field type." }, "max": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Maximum allowed number value or date depending on field type." }, "step": { "type": "number", "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." } } }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels.", "example": 12 }, "font_type": { "type": "string", "description": "Font type of the field value.", "enum": [ "bold", "italic", "bold_italic" ] }, "font": { "type": "string", "description": "Font family of the field value.", "enum": [ "Times", "Helvetica", "Courier" ] }, "color": { "type": "string", "description": "Font color of the field value.", "enum": [ "black", "white", "blue" ], "default": "black" }, "background": { "type": "string", "description": "Field box background color.", "enum": [ "black", "white", "blue" ] }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", "enum": [ "left", "center", "right" ], "default": "left" }, "valign": { "type": "string", "description": "Vertical alignment of the field text value.", "enum": [ "top", "center", "bottom" ], "default": "center" }, "format": { "type": "string", "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", "example": "DD/MM/YYYY" }, "mask": { "description": "Set `true` to make sensitive data masked on the document.", "oneOf": [ { "type": "integer" }, { "type": "boolean" } ], "default": false }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } } } } } } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "preferences", "schema", "fields", "submitters", "author_id", "archived_at", "created_at", "updated_at", "source", "external_id", "folder_id", "folder_name", "author", "documents" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document template." }, "slug": { "type": "string", "description": "Unique slug of the document template." }, "name": { "type": "string", "description": "Name of the template." }, "preferences": { "type": "object", "description": "Template preferences." }, "schema": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "attachment_uuid", "name" ], "properties": { "attachment_uuid": { "type": "string", "description": "Unique indentifier of attached document to the template." }, "name": { "type": "string", "description": "Name of the attached document to the template." } } } }, "fields": { "type": "array", "description": "List of fields to be filled in the template.", "items": { "type": "object", "required": [ "uuid", "submitter_uuid", "name", "type", "required", "areas" ], "properties": { "uuid": { "type": "string", "description": "Unique identifier of the field." }, "submitter_uuid": { "type": "string", "description": "Unique identifier of the submitter that filled the field." }, "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels." }, "font_type": { "type": "string", "description": "Font type of the field value." }, "font": { "type": "string", "description": "Font family of the field value." }, "color": { "type": "string", "description": "Font color of the field value." }, "background": { "type": "string", "description": "Field box background color." }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." }, "valign": { "type": "string", "description": "Vertical alignment of the field text value." }, "format": { "type": "string", "description": "The data format for different field types." }, "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } }, "areas": { "type": "array", "description": "List of areas where the field is located in the document.", "items": { "type": "object", "required": [ "x", "y", "w", "h", "attachment_uuid", "page" ], "properties": { "x": { "type": "number", "description": "X coordinate of the area where the field is located in the document." }, "y": { "type": "number", "description": "Y coordinate of the area where the field is located in the document." }, "w": { "type": "number", "description": "Width of the area where the field is located in the document." }, "h": { "type": "number", "description": "Height of the area where the field is located in the document." }, "attachment_uuid": { "type": "string", "description": "Unique identifier of the attached document where the field is located." }, "page": { "type": "integer", "description": "Page number of the attached document where the field is located." } } } } } } }, "submitters": { "type": "array", "items": { "type": "object", "required": [ "name", "uuid" ], "properties": { "name": { "type": "string", "description": "Submitter name." }, "uuid": { "type": "string", "description": "Unique identifier of the submitter." } } } }, "author_id": { "type": "integer", "description": "Unique identifier of the author of the template." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the template was archived." }, "created_at": { "type": "string", "description": "Date and time when the template was created." }, "updated_at": { "type": "string", "description": "Date and time when the template was updated." }, "source": { "type": "string", "description": "Source of the template.", "enum": [ "native", "api", "embed" ] }, "external_id": { "type": "string", "nullable": true, "description": "Identifier of the template in the external system." }, "folder_id": { "type": "integer", "description": "Unique identifier of the folder where the template is placed." }, "folder_name": { "type": "string", "description": "Folder name where the template is placed." }, "author": { "type": "object", "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the author." }, "first_name": { "type": "string", "description": "First name of the author." }, "last_name": { "type": "string", "description": "Last name of the author." }, "email": { "type": "string", "description": "Author email." } } }, "documents": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "id", "uuid", "url", "preview_image_url", "filename" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document." }, "uuid": { "type": "string", "description": "Unique identifier of the document." }, "url": { "type": "string", "description": "URL of the document." }, "preview_image_url": { "type": "string", "description": "Document preview image URL." }, "filename": { "type": "string", "description": "Document filename." } } } } } }, "example": { "id": 5, "slug": "s3ff992CoPjvaX", "name": "Demo PDF", "schema": [ { "name": "Demo PDF", "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf" } ], "fields": [ { "name": "Name", "type": "text", "required": true, "uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff", "submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7", "areas": [ { "page": 1, "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", "x": 0.403158189124654, "y": 0.04211750189825361, "w": 0.100684625476058, "h": 0.01423690205011389 } ] } ], "submitters": [ { "name": "Submitter", "uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7" } ], "author_id": 1, "archived_at": null, "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z", "source": "api", "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", "author": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, "documents": [ { "id": 7, "uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", "url": "https://app.synexissign.com/hash/DemoPDF.pdf" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/templates/pdf": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Templates" ], "summary": "Create a template from PDF", "description": "Cria um template de documento a partir de um arquivo PDF (base64 ou URL). Os campos podem vir de AcroForm do proprio PDF ou do parametro `fields` (coordenadas normalizadas 0..1, com `role` por signatario). Suporta upsert por `external_id` (substitui os documentos do template existente). **Nota (Synexis Sign):** `flatten` e `remove_tags` sao aceitos e ignorados — text tags `{{...}}` em PDF nao sao suportadas nesta instancia.", "operationId": "createTemplateFromPdf", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "name": { "type": "string", "description": "Name of the template", "example": "Test PDF" }, "folder_name": { "type": "string", "description": "The folder's name to which the template should be created." }, "external_id": { "type": "string", "description": "Your application-specific unique string key to identify this template within your app. Existing template with specified `external_id` will be updated with a new PDF.", "example": "unique-key" }, "documents": { "type": "array", "items": { "type": "object", "required": [ "name", "file" ], "properties": { "name": { "type": "string", "description": "Name of the document." }, "file": { "example": "base64", "type": "string", "format": "base64", "description": "Base64-encoded content of the PDF file or downloadable file URL." }, "fields": { "type": "array", "description": "Fields are optional if you use {{...}} text tags to define fields in the document.", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the field." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "role": { "type": "string", "description": "Role name of the signer." }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "title": { "type": "string", "description": "Field title displayed to the user instead of the name, shown on the signing form. Supports Markdown." }, "description": { "type": "string", "description": "Field description displayed on the signing form. Supports Markdown." }, "areas": { "type": "array", "items": { "type": "object", "required": [ "x", "y", "w", "h", "page" ], "properties": { "x": { "type": "number", "description": "X-coordinate of the field area." }, "y": { "type": "number", "description": "Y-coordinate of the field area." }, "w": { "type": "number", "description": "Width of the field area." }, "h": { "type": "number", "description": "Height of the field area." }, "page": { "type": "integer", "description": "Page number of the field area. Starts from 1.", "example": 1 }, "option": { "type": "string", "description": "Option string value for 'radio' and 'multiple' select field types." } } } }, "options": { "type": "array", "description": "An array of option values for 'select' field type.", "items": { "type": "string" }, "example": [ "Option A", "Option B" ] }, "validation": { "type": "object", "properties": { "pattern": { "type": "string", "description": "HTML field validation pattern string based on https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/pattern specification.", "example": "[A-Z]{4}" }, "message": { "type": "string", "description": "A custom error message to display on validation failure." }, "min": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Minimum allowed number value or date depending on field type." }, "max": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "description": "Maximum allowed number value or date depending on field type." }, "step": { "type": "number", "description": "Increment step for number field. Pass 1 to accept only integers, or 0.01 to accept decimal currency." } } }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels.", "example": 12 }, "font_type": { "type": "string", "description": "Font type of the field value.", "enum": [ "bold", "italic", "bold_italic" ] }, "font": { "type": "string", "description": "Font family of the field value.", "enum": [ "Times", "Helvetica", "Courier" ] }, "color": { "type": "string", "description": "Font color of the field value.", "enum": [ "black", "white", "blue" ], "default": "black" }, "background": { "type": "string", "description": "Field box background color.", "enum": [ "black", "white", "blue" ] }, "align": { "type": "string", "description": "Horizontal alignment of the field text value.", "enum": [ "left", "center", "right" ], "default": "left" }, "valign": { "type": "string", "description": "Vertical alignment of the field text value.", "enum": [ "top", "center", "bottom" ], "default": "center" }, "format": { "type": "string", "description": "The data format for different field types.
- Date field: accepts formats such as DD/MM/YYYY (default: MM/DD/YYYY).
- Signature field: accepts drawn, typed, drawn_or_typed (default), or upload.
- Number field: accepts currency formats such as usd, eur, gbp.", "example": "DD/MM/YYYY" }, "mask": { "description": "Set `true` to make sensitive data masked on the document.", "oneOf": [ { "type": "integer" }, { "type": "boolean" } ], "default": false }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } } } } } } } }, "flatten": { "type": "boolean", "description": "Remove PDF form fields from the documents.", "default": false }, "remove_tags": { "type": "boolean", "description": "Pass `false` to disable the removal of {{text}} tags from the PDF. This can be used along with transparent text tags for faster and more robust PDF processing.", "default": true } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "id", "slug", "name", "preferences", "schema", "fields", "submitters", "author_id", "archived_at", "created_at", "updated_at", "source", "external_id", "folder_id", "folder_name", "author", "documents" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document template." }, "slug": { "type": "string", "description": "Unique slug of the document template." }, "name": { "type": "string", "description": "Name of the template." }, "preferences": { "type": "object", "description": "Template preferences." }, "schema": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "attachment_uuid", "name" ], "properties": { "attachment_uuid": { "type": "string", "description": "Unique indentifier of attached document to the template." }, "name": { "type": "string", "description": "Name of the attached document to the template." } } } }, "fields": { "type": "array", "description": "List of fields to be filled in the template.", "items": { "type": "object", "required": [ "uuid", "submitter_uuid", "name", "type", "required", "areas" ], "properties": { "uuid": { "type": "string", "description": "Unique identifier of the field." }, "submitter_uuid": { "type": "string", "description": "Unique identifier of the submitter that filled the field." }, "name": { "type": "string", "description": "Field name." }, "type": { "type": "string", "description": "Type of the field (e.g., text, signature, date, initials).", "enum": [ "heading", "text", "signature", "initials", "date", "number", "image", "checkbox", "multiple", "file", "radio", "select", "cells", "stamp", "phone", "strikethrough" ] }, "required": { "type": "boolean", "description": "Indicates if the field is required." }, "preferences": { "type": "object", "properties": { "font_size": { "type": "integer", "description": "Font size of the field value in pixels." }, "font_type": { "type": "string", "description": "Font type of the field value." }, "font": { "type": "string", "description": "Font family of the field value." }, "color": { "type": "string", "description": "Font color of the field value." }, "background": { "type": "string", "description": "Field box background color." }, "align": { "type": "string", "description": "Horizontal alignment of the field text value." }, "valign": { "type": "string", "description": "Vertical alignment of the field text value." }, "format": { "type": "string", "description": "The data format for different field types." }, "mask": { "type": "boolean", "description": "Indicates if the field is masked on the document." }, "reasons": { "description": "An array of signature reasons to choose from.", "type": "array", "items": { "type": "string" } } } }, "areas": { "type": "array", "description": "List of areas where the field is located in the document.", "items": { "type": "object", "required": [ "x", "y", "w", "h", "attachment_uuid", "page" ], "properties": { "x": { "type": "number", "description": "X coordinate of the area where the field is located in the document." }, "y": { "type": "number", "description": "Y coordinate of the area where the field is located in the document." }, "w": { "type": "number", "description": "Width of the area where the field is located in the document." }, "h": { "type": "number", "description": "Height of the area where the field is located in the document." }, "attachment_uuid": { "type": "string", "description": "Unique identifier of the attached document where the field is located." }, "page": { "type": "integer", "description": "Page number of the attached document where the field is located." } } } } } } }, "submitters": { "type": "array", "items": { "type": "object", "required": [ "name", "uuid" ], "properties": { "name": { "type": "string", "description": "Submitter name." }, "uuid": { "type": "string", "description": "Unique identifier of the submitter." } } } }, "author_id": { "type": "integer", "description": "Unique identifier of the author of the template." }, "archived_at": { "type": "string", "nullable": true, "description": "Date and time when the template was archived." }, "created_at": { "type": "string", "description": "Date and time when the template was created." }, "updated_at": { "type": "string", "description": "Date and time when the template was updated." }, "source": { "type": "string", "description": "Source of the template.", "enum": [ "native", "api", "embed" ] }, "external_id": { "type": "string", "nullable": true, "description": "Identifier of the template in the external system." }, "folder_id": { "type": "integer", "description": "Unique identifier of the folder where the template is placed." }, "folder_name": { "type": "string", "description": "Folder name where the template is placed." }, "author": { "type": "object", "required": [ "id", "first_name", "last_name", "email" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the author." }, "first_name": { "type": "string", "description": "First name of the author." }, "last_name": { "type": "string", "description": "Last name of the author." }, "email": { "type": "string", "description": "Author email." } } }, "documents": { "type": "array", "description": "List of documents attached to the template.", "items": { "type": "object", "required": [ "id", "uuid", "url", "preview_image_url", "filename" ], "properties": { "id": { "type": "integer", "description": "Unique identifier of the document." }, "uuid": { "type": "string", "description": "Unique identifier of the document." }, "url": { "type": "string", "description": "URL of the document." }, "preview_image_url": { "type": "string", "description": "Document preview image URL." }, "filename": { "type": "string", "description": "Document filename." } } } } } }, "example": { "id": 5, "slug": "s3ff992CoPjvaX", "name": "Demo PDF", "schema": [ { "name": "Demo PDF", "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf" } ], "fields": [ { "name": "Name", "type": "text", "required": true, "uuid": "d0bf3c0c-1928-40c8-80f9-d9f3c6ad4eff", "submitter_uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7", "areas": [ { "page": 1, "attachment_uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", "x": 0.403158189124654, "y": 0.04211750189825361, "w": 0.100684625476058, "h": 0.01423690205011389 } ] } ], "submitters": [ { "name": "Submitter", "uuid": "0b0bff58-bc9a-475d-b4a9-2f3e5323faf7" } ], "author_id": 1, "archived_at": null, "created_at": "2023-12-14T15:50:21.799Z", "updated_at": "2023-12-14T15:50:21.799Z", "source": "api", "folder_id": 1, "folder_name": "Default", "external_id": "c248ffba-ef81-48b7-8e17-e3cecda1c1c5", "author": { "id": 1, "first_name": "John", "last_name": "Doe", "email": "john.doe@example.com" }, "documents": [ { "id": 7, "uuid": "48d2998f-266b-47e4-beb2-250ab7ccebdf", "url": "https://app.synexissign.com/file/hash/Demo%20PDF.pdf" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/account/usage": { "get": { "summary": "Consumo da franquia da conta", "description": "Plano e uso do periodo corrente (mes-calendario) da conta autenticada. Integracao CRM: consulte com o token do proprio tenant para exibir \"X de N assinaturas\".", "tags": [ "Account" ], "responses": { "200": { "description": "Plano, consumo por recurso e fim do periodo", "content": { "application/json": { "schema": { "type": "object", "properties": { "plan": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" } } }, "usage": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "string", "example": "submissions_per_month" }, "used": { "type": "integer" }, "limit": { "type": "integer", "nullable": true }, "unlimited": { "type": "boolean" } } } }, "period_end": { "type": "string", "format": "date" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "AuthToken": [] } ] } }, "/account/settings": { "get": { "summary": "Configuracoes da conta que afetam a integracao", "description": "Le as configs da conta autenticada que mudam o comportamento do envio e do download — o que um integrador precisava adivinhar ou hardcodar: require_signer_cpf (ligado, uma submissao sem CPF valido e recusada) e combine_pdf_result (ligado, o download devolve um unico PDF combinado; desligado, os arquivos separados). Inclui o ambiente da chave usada ('sandbox' na conta de teste vinculada, 'production' na conta normal). Consulte ANTES de montar o envelope, nao depois do 422. Atencao: combine_pdf_result e o toggle da CONTA; envelopes com assinatura qualificada nunca sao combinados, independente do toggle.", "tags": [ "Account" ], "responses": { "200": { "description": "Ambiente da chave e configs relevantes para a integracao", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string", "enum": [ "production", "sandbox" ] }, "require_signer_cpf": { "type": "boolean" }, "combine_pdf_result": { "type": "boolean" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } }, "security": [ { "AuthToken": [] } ] } }, "/certificates": { "get": { "security": [ { "AuthToken": [] } ], "tags": [ "Certificates" ], "summary": "List vault certificates", "description": "Lists the active ICP-Brasil certificates stored in the account vault. Read-only: there is no API endpoint to import certificates or export private keys. Responds 404 unless certificate vault automation is enabled for the account.", "operationId": "getCertificates", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "certificates" ], "properties": { "certificates": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "description": "Public identifier of the vault entry." }, "label": { "type": "string", "nullable": true, "description": "Label given by the account." }, "kind": { "type": "string", "enum": [ "e_cpf", "e_cnpj" ], "description": "Certificate kind." }, "subject": { "type": "string", "description": "Certificate subject CN." }, "holder": { "type": "string", "nullable": true, "description": "Certificate holder name." }, "status": { "type": "string", "description": "Entry status (active)." }, "valid_until": { "type": "string", "nullable": true, "description": "Certificate expiry (ISO 8601)." }, "pin_protected": { "type": "boolean", "description": "Whether the entry requires the holder PIN." }, "automation_eligible": { "type": "boolean", "description": "Whether this entry can sign via API/MCP: usable, e-CNPJ and not PIN-protected." } } } } } } } } } } } }, "/submitters/{id}/sign_with_certificate": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Certificates" ], "summary": "Sign as submitter with a vault certificate", "description": "Queues a qualified ICP-Brasil signature for a pending submitter using a certificate from the account vault. The signature itself is asynchronous: 202 means queued — follow up with GET /submitters/{id} or the submitter.completed webhook. Requires an automation grant for the API token; e-CPF and PIN-protected certificates never sign via automation. Supports Idempotency-Key to make retries safe.", "operationId": "signSubmitterWithCertificate", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submitter.", "example": 500001 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "certificate_uuid" ], "properties": { "certificate_uuid": { "type": "string", "description": "UUID of the vault certificate (from GET /certificates)." }, "values": { "type": "object", "description": "Optional field values to fill before signing, keyed by field name." } } } } } }, "responses": { "202": { "description": "Accepted — signature queued", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "submitter_id", "certificate_uuid" ], "properties": { "status": { "type": "string", "enum": [ "queued" ] }, "submitter_id": { "type": "integer" }, "certificate_uuid": { "type": "string" } } } } } }, "403": { "description": "Forbidden — no automation grant for this token, IP not allowed, or account not entitled." }, "422": { "description": "Unprocessable — certificate not available, e-CPF automation, PIN-protected entry, or missing required values." }, "429": { "description": "Too many requests — daily limit of the automation grant reached." } } } }, "/folders": { "get": { "tags": [ "Folders" ], "summary": "List folders", "operationId": "getFolders", "security": [ { "AuthToken": [] } ], "description": "Lista as pastas ativas da conta (sem as pastas de sistema: Default e a do envio rapido). Use o full_name em folder_name ao criar ou mover um envelope.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "example": "Acme" }, "full_name": { "type": "string", "example": "Clientes / Acme", "description": "Nome completo com o pai, separado por \" / \"." }, "parent_id": { "type": [ "integer", "null" ], "example": 41 }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "full_name", "parent_id", "created_at" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } }, "post": { "tags": [ "Folders" ], "summary": "Create folder", "operationId": "createFolder", "security": [ { "AuthToken": [] } ], "description": "Cria uma pasta pelo nome. \"Pai / Filha\" cria os dois niveis. Idempotente por nome: um nome que ja existe devolve a pasta existente (201) em vez de duplicar. Nome vazio ou nome de pasta de sistema responde 422 com code folder.invalid_name.", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Clientes / Acme", "description": "Nome da pasta; \"Pai / Filha\" cria a hierarquia." } } } } } }, "responses": { "201": { "description": "Pasta criada (ou a existente com esse nome)", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "example": 42 }, "name": { "type": "string", "example": "Acme" }, "full_name": { "type": "string", "example": "Clientes / Acme", "description": "Nome completo com o pai, separado por \" / \"." }, "parent_id": { "type": [ "integer", "null" ], "example": 41 }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "full_name", "parent_id", "created_at" ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } }, "/submissions/{id}/unarchive": { "post": { "security": [ { "AuthToken": [] } ], "tags": [ "Submissions" ], "summary": "Unarchive a submission", "operationId": "unarchiveSubmission", "description": "Desfaz o DELETE (que arquiva): o envelope volta a tela do remetente. Nao dispara evento de webhook. Envelope de outra conta responde 403; id inexistente, 404.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique identifier of the submission.", "example": 1001 }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "archived_at": { "type": "null" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "Envelope inexistente" }, "429": { "$ref": "#/components/responses/TooManyRequests" } } } } } }