Assignments

Create assignment (request signatures)

Changed on

Request signatures on a document. Use method: virtual to sign without input fields, or method: collect to place input fields on specific pages.

Digital certificate signing works only on virtual assignments. A DigitalCertificate signer cannot sign placed fields, so a collect assignment with one is refused with 400 before anything is charged.

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

post/v1/documents/{documentId}/assignments

Request

  • Base URL
    https://api.assinafy.com.br
  • URL
    https://api.assinafy.com.br/v1/documents/{documentId}/assignments
  • Auth
    • HTTP bearer
    • or API key in header X-Api-Key

Path parameters

documentIdstring required

Document ID.

Request body

method'virtual' | 'collect' required

virtual signs without input fields; collect places input fields on pages. Signers with DigitalCertificate verification need virtual (collect returns 400).

messagestring

Text included in the invitation email.

expires_atstring date-time

ISO 8601; default is no expiration. 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.

copy_receiversstring[]

Signer IDs that only receive a copy.

Example request

{
  "method": "virtual",
  "signers": [
    {
      "id": "615605f50e968054a5b7c9b8",
      "verification_method": "Email",
      "notification_methods": [
        "Email"
      ],
      "step": 1
    }
  ],
  "entries": [
    {
      "fields": [
        {
          "display_settings": {
            "left": 69,
            "top": 282,
            "width": 421,
            "height": 45.86,
            "fontFamily": "Arial",
            "fontSize": 22,
            "backgroundColor": "#D5EBFF"
          }
        }
      ]
    }
  ]
}

Response

The created assignment

statusinteger

HTTP status code, mirrored in the body.

messagestring

Human-readable message; empty on success.

Example response

{
  "status": 200,
  "data": {
    "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"
      }
    ]
  }
}

Changes

  • f7da81a5567eRevision changes
    • breaking

      the response property // became nullable for the status

  • dda5f0d393cbRevision changes
    • info

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

    • info

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