Documents

Create document from template

Changed on

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 Open in ChatGPT Open in Claude

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
    • HTTP bearer
    • or API key in header X-Api-Key

Path parameters

accountIdstring required

Workspace account ID.

templateIdstring required

The template ID.

Request body

namestring

Title for the document. Defaults to the template name.

messagestring

Optional message sent to signers.

expires_atstring 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.

tagsstring[]

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).

Example request

{
  "signers": [
    {
      "role_id": "fa8c14f32d732271e071998246e",
      "id": "fa8c140cb49b79f940aab95fddd",
      "email": "signer@example.com",
      "name": "Maria Silva",
      "whatsapp_phone_number": "+5548999999999",
      "verification_method": "Email",
      "notification_methods": [
        "Email"
      ],
      "step": 1
    }
  ],
  "editor_fields": [
    {
      "field_id": "fa8c14f3af99d2846d1789de4ba",
      "value": "Field value"
    }
  ],
  "name": "sample-contract-one-page.pdf",
  "message": "Message to the signers",
  "expires_at": "2024-07-30T23:59:00Z"
}

Response

The created document

statusinteger

HTTP status code, mirrored in the body.

messagestring

Human-readable message; empty on success.

Example response

{
  "status": 200,
  "data": {
    "resource": "document",
    "id": "615601fab04c0a3147bb1246",
    "account_id": "d199996981dbd199996981db",
    "name": "document.pdf",
    "status": "metadata_ready",
    "artifacts": {
      "original": "https://api.assinafy.com.br/v1/documents/doc1/download/original"
    },
    "signing_url": "https://api.assinafy.com.br/v1/sign/doc1",
    "verification_code": "a3f1c9e07b2d4e8f9a6c5b1d0e7f3a2c9b8d4e6f",
    "verification_url": "https://www.assinafy.com.br/verificador/a3f1c9e07b2d4e8f9a6c5b1d0e7f3a2c9b8d4e6f",
    "declined_by": {
      "resource": "signer",
      "id": "62d6ee35c7741ca4006b9e11",
      "full_name": "John Signer",
      "email": "john@email.com",
      "whatsapp_phone_number": "+5548999990000",
      "government_id": "39053344705"
    },
    "assignment": {
      "resource": "assignment",
      "id": "615606ef81d199996981dbce",
      "document_id": "615601fab04c0a3147bb1246",
      "created_at": "2026-06-03T03:54:16Z",
      "sender_email": "sender@example.com",
      "method": "virtual",
      "signers": [
        {
          "resource": "signer",
          "id": "62d6ee35c7741ca4006b9e11",
          "full_name": "John Signer",
          "email": "john@email.com",
          "whatsapp_phone_number": "+5548999990000",
          "government_id": "39053344705",
          "verification_method": "Email",
          "notification_methods": [
            "Email"
          ],
          "step": 1,
          "identity_verification_status": "InReview",
          "notification_history": [
            {
              "event": "signature_request",
              "status": "sent",
              "sent_at": "2026-07-07T12:00:00Z"
            }
          ]
        }
      ],
      "items": [
        {
          "page": {
            "id": "615601faf166d6d1d8e7dc30",
            "number": 1,
            "height": 2100,
            "width": 1275,
            "download_url": "https://api.assinafy.com.br/v1/documents/doc1/pages/1a/download"
          }
        }
      ],
      "signing_urls": [
        {
          "url": "https://api.assinafy.com.br/v1/sign/doc1?email=joe@example.com"
        }
      ]
    },
    "pages": [
      {
        "id": "615601faf166d6d1d8e7dc30",
        "number": 1,
        "height": 2100,
        "width": 1275,
        "download_url": "https://api.assinafy.com.br/v1/documents/doc1/pages/1a/download"
      }
    ],
    "created_at": "2026-06-03T03:54:16Z",
    "updated_at": "2026-06-03T03:54:16Z"
  }
}

Changes

  • f7da81a5567eRevision changes
    • breaking

      the response property /////// became nullable for the status

  • dda5f0d393cbRevision changes
    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      added the new optional request property //

    • info

      the request property // became optional

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property /////// to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property // to the response with the status