--- title: "Create assignment (request signatures)" method: POST path: "/v1/documents/{documentId}/assignments" tags: ["Assignments"] --- # Create assignment (request signatures) `POST /v1/documents/{documentId}/assignments` Request signatures on a document. Use `method: virtual` to sign without input fields, or `method: collect` to place input fields on specific pages. For **virtual**, the document may be in `uploaded`, `metadata_processing` or `metadata_ready`; it is promoted to `pending_signature` automatically once metadata processing completes. For **collect**, the document must be in `metadata_ready` (fields reference specific pages). `step` controls signing order: signers sharing a step sign in parallel, and the next step is notified only after the previous step completes. If supplied, every signer must supply it and values must be contiguous starting at 1. [Copy as Markdown](https://api.assinafy.com.br/v1/docs/markdown?method=post&path=%2Fv1%2Fdocuments%2F%7BdocumentId%7D%2Fassignments) [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%252Fdocuments%252F%257BdocumentId%257D%252Fassignments%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%252Fdocuments%252F%257BdocumentId%257D%252Fassignments%20and%20help%20me%20integrate%20this%20endpoint.) ## Path parameters - `documentId` string, required ## Request body - object - `method` 'virtual' | 'collect', required - `signers` object[], required - `id` string, required - `verification_method` 'Email' | 'Whatsapp' | 'DigitalCertificate' — How the signer's identity is verified before signing. `Email` (default) sends a one-time code to the signer's email; `Whatsapp` sends the code over WhatsApp (incurs an additional cost and is available only on paid subscriptions); `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate (A1/A3) — it requires the Digital Certificate feature, the signer must have a CPF or CNPJ in `government_id`, must be alone in its signing step, and is charged 2 credits per signer. A CPF requires that person's certificate (an e-CPF, or an e-CNPJ naming them as legal representative); a CNPJ requires an e-CNPJ for that company, from any of its representatives. Omit to default to `Email`. - `notification_methods` string[] — Channels used to notify the signer of the request. Any combination of `Email` and `Whatsapp` (WhatsApp incurs an additional cost and is available only on paid subscriptions). Omit to default to `{"Email"}`. - `step` integer - `entries` object[] — Required for `collect`: field placements per page. - `page_id` string - `fields` object[] - `signer_id` string - `field_id` string - `display_settings` DisplaySettings — A field placement rectangle on a document page. Geometry values are pixels in Assinafy's 150-DPI page image, measured from the upper-left corner. Clients must keep the rectangle within the selected page's width and height; the API does not clamp out-of-bounds values. - `left` number, float, required — Horizontal distance from the page's left edge, in page-image pixels. - `top` number, float, required — Vertical distance from the page's top edge, in page-image pixels. - `width` number, float, required — Width of the placement rectangle, in page-image pixels. - `height` number, float, required — Height of the placement rectangle, in page-image pixels. - `fontFamily` string — Font-family presentation metadata. - `fontSize` number, float, required — Font size in the 150-DPI page-image coordinate system. - `backgroundColor` string — CSS-compatible background-color presentation metadata. - `message` string — Text included in the invitation email. - `expires_at` string, date-time — ISO 8601; default is no expiration. - `copy_receivers` string[] — Signer IDs that only receive a copy. ## Response `200` The created assignment - 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` Assignment — A request for signers to sign a document. - `resource` string - `id` string - `sender_email` string, email - `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. - `has_accepted_terms` boolean - `verification_method` string, nullable - `notification_methods` string[], nullable - `step` integer, nullable — Sequential signing step (defaults to 1). - `notified` boolean, nullable - `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 ## Other responses - `400` — One or more fields failed validation. - `401` — Missing or invalid credentials. - `500` — Unexpected server error. --- [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-service-production.skmtc.workers.dev/v1/apis/assinafy/assinafy-api-reference/revisions/f479941d10e9/schema)