--- title: "Create document from template" method: POST path: "/v1/accounts/{accountId}/templates/{templateId}/documents" tags: ["Documents"] --- # Create document from template `POST /v1/accounts/{accountId}/templates/{templateId}/documents` ## Request - Base URL: `https://api.assinafy.com.br` - URL: `https://api.assinafy.com.br/v1/accounts/{accountId}/templates/{templateId}/documents` - Auth: one of: - HTTP bearer - API key in header `X-Api-Key` Generate a new document from a template. The request is checked (roles, fields, balance) before it returns, but the assignment is created in the background, so the response has `status: uploaded` and `assignment: null`. Follow the outcome on `GET /v1/documents/{documentId}` or through webhooks: when the send succeeds the status moves to `pending_signature` and `assignment_created` is sent; when it fails the status becomes `failed`, `document_processing_failed` is sent with the reason, and nothing is charged. When the template has fields, every signing role used must have at least one field; otherwise `400`. A template with placed signer fields sends a `collect` assignment, so it cannot take a `DigitalCertificate` signer (`400`); certificate signing needs a template without placed signer fields. Provide one signer entry per template role. An entry with `id` uses that existing signer; an entry with `email` reuses the account's signer with that email or creates one. [Copy as Markdown](https://api.assinafy.com.br/v1/docs/markdown?method=post&path=%2Fv1%2Faccounts%2F%7BaccountId%7D%2Ftemplates%2F%7BtemplateId%7D%2Fdocuments) [Open in ChatGPT](https://chatgpt.com/?q=Read%20the%20API%20documentation%20at%20https%3A%2F%2Fapi.assinafy.com.br%2Fv1%2Fdocs%2Fmarkdown%3Fmethod%3Dpost%26path%3D%252Fv1%252Faccounts%252F%257BaccountId%257D%252Ftemplates%252F%257BtemplateId%257D%252Fdocuments%20and%20help%20me%20integrate%20this%20endpoint.) [Open in Claude](https://claude.ai/new?q=Read%20the%20API%20documentation%20at%20https%3A%2F%2Fapi.assinafy.com.br%2Fv1%2Fdocs%2Fmarkdown%3Fmethod%3Dpost%26path%3D%252Fv1%252Faccounts%252F%257BaccountId%257D%252Ftemplates%252F%257BtemplateId%257D%252Fdocuments%20and%20help%20me%20integrate%20this%20endpoint.) ## Path parameters - `accountId` string, required - `templateId` string, required ## Request body - object - `signers` object[], required: One entry per template role. - `role_id` string, required: The template role ID associated with the signer. - `id` string: An existing signer's ID. Send either `id` or `email`; `id` wins when both are sent, and an unknown `id` returns `400`. - `email` string: Used when `id` is not sent: the account's signer with this email is reused, or a new one is created with `name`. - `name` string: Full name for a signer created from `email`. - `whatsapp_phone_number` string: WhatsApp number for a signer created from `email`. - `verification_method` 'Email' | 'Whatsapp' | 'DigitalCertificate' | 'IdDocumentFaceMatchBasic': Verification method for this signer. If provided without notification_methods, the notification method is inferred. Defaults to Email. `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate — it requires the Digital Certificate feature, the signer must have a CPF or CNPJ in `government_id` (a CPF requires that person's certificate; a CNPJ requires an e-CNPJ for that company), must be alone in its signing step, and is charged 0.5 credits per signer. It is refused with `400` when the template has placed signer fields, because certificate signers sign only virtual assignments. `IdDocumentFaceMatchBasic` verifies the signer from a photo of their government ID, a photo of them holding it and a liveness check — it requires the ID Document + Face Match feature, the signer must have a valid CPF in `government_id`, and is charged a per-signer fee. Only applies to signers (not copy receivers). - `notification_methods` string[]: Notification method codes for this signer. If provided without verification_method, the verification method is inferred. Defaults to Email. Only one method allowed per signer. - `step` integer: Positive integer that controls signing order. Signers sharing the same step sign in parallel; a step activates only after every signer in the previous step has signed. If supplied for any role it must be supplied for all, forming a contiguous sequence starting at 1. Copy receivers ignore this field. - `editor_fields` object[]: Values for the fields placed on the template's `Editor` role, baked into the generated document. The `Editor` role takes no `signers` entry: it is filled only through this list. Every field placed on it needs an entry with a non-empty `value` (`400` otherwise); when it has no fields, send nothing. In `signers`, every `Signer` role needs an entry (`400` otherwise), and a `CopyReceiver` role takes an entry only for someone who should receive the certified document; a copy receiver's `verification_method`, `notification_methods` and `step` are ignored. - `field_id` string, required: The field identifier, matching the field_id in the template data. - `value` string, required: The value to assign to the field. - `name` string: Title for the document. Defaults to the template name. - `message` string: Optional message sent to signers. - `expires_at` string, date-time: Assignment expiration date (ISO 8601). No expiration by default. Must be at least one hour in the future. A UTC offset in the value is honored (`2026-12-31T23:59:59-03:00` is `2027-01-01T02:59:59Z`); a value without one is read as UTC, and a date alone (`2026-12-31`) means 23:59 UTC that day. - `tags` string[]: Tag names to attach to the new document. Names that don't exist are auto-created. The template's default-document-tags are always applied; values here are merged on top (duplicates removed). ## Response `200` The created document - object: Standard success wrapper. Operations add their own `data`. - `status` integer: HTTP status code, mirrored in the body. - `message` string: Human-readable message; empty on success. - `data` Document: A document and its current lifecycle state. - `resource` string: Present in single-resource responses. - `id` string - `account_id` string - `template_id` string, nullable - `name` string - `status` string: Status code — see GET /v1/documents/statuses. - `artifacts` object: Artifact download URLs keyed by name. Always `original`, plus `thumbnail` once one exists. A certificated document also carries `certificated`, `certificate-page` and `bundle`, and `pades` when it was signed with a digital certificate — the PAdES version holds the signers' ICP-Brasil signatures, which certification flattens out of the certificated PDF. - `is_closed` boolean - `signing_url` string - `verification_code` string, nullable: The code printed on the certificate page. Anyone can check it with `GET /v1/documents/{verification_code}/verify` or on `verification_url`. `null` until the document is `certificated`, and on documents certificated before verification codes existed. - `verification_url` string, uri, nullable: The public verification page for this document. `null` until the document is `certificated`. - `decline_reason` string, nullable - `declined_by` Signer: A signing party belonging to a workspace account. - `resource` string: Present in single-resource responses. - `id` string - `full_name` string - `email` string, email, nullable - `whatsapp_phone_number` string, nullable: E.164 format; normalized on save. - `government_id` string, nullable: Signer's normalized CPF (11 digits) or CNPJ (14 characters; may be alphanumeric). - `has_accepted_terms` boolean - `tags` object[] - `id` string - `name` string - `assignment` Assignment: A request for signers to sign a document. - `resource` string - `id` string - `document_id` string, nullable: The document this assignment belongs to. `null` only if the document was deleted. - `created_at` string, date-time - `sender_email` string, email, nullable: Email of the user who sent the document; null once that user has deleted their account. - `method` 'virtual' | 'collect' - `expires_at` string, date-time, nullable - `message` string, nullable - `signers` AssignmentSigner[] - `resource` string: Present in single-resource responses. - `id` string - `full_name` string - `email` string, email, nullable - `whatsapp_phone_number` string, nullable: E.164 format; normalized on save. - `government_id` string, nullable: Signer's normalized CPF (11 digits) or CNPJ (14 characters; may be alphanumeric). - `has_accepted_terms` boolean - `verification_method` string, nullable - `notification_methods` string[], nullable - `step` integer, nullable: Sequential signing step (defaults to 1). - `notified` boolean, nullable - `identity_verification_status` 'Pending' | 'InReview' | 'Approved' | 'Declined' | 'Expired' | 'Abandoned', nullable: Latest identity-document verification status; `InReview` means the account must decide it before the document can be certificated. - `completed` boolean, nullable: Only present in account-owner contexts. - `notification_history` NotificationHistoryEntry[], nullable: Per-channel delivery history for this signer (email + WhatsApp), most-recent send order. - `event` string - `status` 'sent' | 'failed' - `error_code` string, nullable - `error_message` string, nullable - `sent_at` string, date-time, nullable - `failed_at` string, date-time, nullable - `copy_receivers` object[] - `items` AssignmentItem[] - `id` string - `page` DocumentPage - `id` string - `number` integer - `height` integer - `width` integer - `download_url` string - `signer` object: Signer responsible for this item. - `field` object, nullable: Field definition associated with the item. - `display_settings` unknown - `value` unknown - `completed` boolean - `summary` AssignmentSummary - `signer_count` integer - `completed_count` integer - `signers` object[] - `signing_urls` SigningUrl[] - `signer_id` string - `url` string - `pages` DocumentPage[]: The document's pages. Included on the same responses as `assignment`, and also on the upload response. - `id` string - `number` integer - `height` integer - `width` integer - `download_url` string - `created_at` string, date-time - `updated_at` string, date-time ## Other responses - `400`: One or more fields failed validation. - `401`: Missing or invalid credentials. - `500`: Unexpected server error. ## Changes - **2026-10-26** `f7da81a5567e`: 1 breaking - the response property `allOf[subschema #2]/data/assignment/oneOf[#/components/schemas/Assignment]/sender_email` became nullable for the status `200` - **2026-10-22** `dda5f0d393cb`: 8 info - added the new optional request property `signers/items/email` - added the new optional request property `signers/items/name` - added the new optional request property `signers/items/whatsapp_phone_number` - the request property `signers/items/id` became optional - …4 more - **2026-10-15** `da98836f863b`: 2 info - added the new `IdDocumentFaceMatchBasic` enum value to the request property `signers/items/verification_method` - added the optional property `allOf[subschema #2]/data/assignment/oneOf[#/components/schemas/Assignment]/signers/items/allOf[subschema #2]/identity_verification_status` to the response with the `200` status - …earlier changes not shown [Operation history](https://skmtc.dev/assinafy/apis/assinafy-api-reference/changes/v1/accounts/:accountId/templates/:templateId/documents/post.md) --- [API](https://skmtc.dev/assinafy/apis/assinafy-api-reference.md) - [All operations](https://skmtc.dev/assinafy/apis/assinafy-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/assinafy/apis/assinafy-api-reference/revisions/f7da81a5567e?raw)