Input schema (JSON)
{
"type": "object",
"allOf": [
{
"if": {
"required": [
"method"
],
"properties": {
"method": {
"const": "collect"
}
}
},
"then": {
"required": [
"entries"
],
"properties": {
"entries": {
"minItems": 1
}
}
}
},
{
"if": {
"required": [
"estimate_only"
],
"properties": {
"estimate_only": {
"const": true
}
}
},
"else": {
"properties": {
"signers": {
"items": {
"required": [
"id"
]
}
}
}
}
}
],
"required": [
"method",
"signers",
"document_id"
],
"properties": {
"method": {
"enum": [
"virtual",
"collect"
],
"type": "string",
"default": "virtual"
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"page_id",
"fields"
],
"properties": {
"fields": {
"type": "array",
"items": {
"type": "object",
"required": [
"signer_id",
"field_id",
"display_settings"
],
"properties": {
"field_id": {
"type": "string"
},
"signer_id": {
"type": "string"
},
"display_settings": {
"type": "object",
"required": [
"left",
"top",
"width",
"height",
"fontSize"
],
"properties": {
"top": {
"type": "number",
"format": "float",
"minimum": 0,
"description": "Vertical distance from the page's top edge, in page-image pixels."
},
"left": {
"type": "number",
"format": "float",
"minimum": 0,
"description": "Horizontal distance from the page's left edge, in page-image pixels."
},
"width": {
"type": "number",
"format": "float",
"description": "Width of the placement rectangle, in page-image pixels.",
"exclusiveMinimum": 0
},
"height": {
"type": "number",
"format": "float",
"description": "Height of the placement rectangle, in page-image pixels.",
"exclusiveMinimum": 0
},
"fontSize": {
"type": "number",
"format": "float",
"description": "Font size in the 150-DPI page-image coordinate system.",
"exclusiveMinimum": 0
},
"fontFamily": {
"type": "string",
"description": "Font-family presentation metadata."
},
"backgroundColor": {
"type": "string",
"description": "CSS-compatible background-color presentation metadata."
}
},
"description": "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.",
"additionalProperties": false
}
},
"additionalProperties": false
},
"minItems": 1
},
"page_id": {
"type": "string"
}
},
"additionalProperties": false
},
"description": "Required for `collect`: field placements per page."
},
"message": {
"type": "string",
"description": "Text included in the invitation email."
},
"signers": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"step": {
"type": "integer",
"minimum": 1
},
"verification_method": {
"enum": [
"Email",
"Whatsapp",
"DigitalCertificate",
"IdDocumentFaceMatchBasic"
],
"type": "string",
"example": "Email",
"description": "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 — the verification itself is not billed, but it requires the WhatsApp notification channel, so the signer costs 0.45 credits (available only on paid subscriptions); `DigitalCertificate` has the signer sign with their own ICP-Brasil certificate (A1/A3) — it requires `method: virtual`, the Digital Certificate feature, a CPF or CNPJ in `government_id`, must be alone in its signing step, and is charged 0.5 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. `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. Omit to default to `Email`."
},
"notification_methods": {
"type": "array",
"items": {
"enum": [
"Email",
"Whatsapp"
],
"type": "string"
},
"example": [
"Email"
],
"maxItems": 1,
"description": "How the signer is told a signature is being requested. **Exactly one method per signer** — the array shape is historical, and sending two returns `400`. The method must also be compatible with `verification_method`: `Email` verification takes `Email`, `Whatsapp` verification takes `Whatsapp`, and `DigitalCertificate` and `IdDocumentFaceMatchBasic` take either. WhatsApp incurs an additional cost and is available only on paid subscriptions. Omit it to have it inferred from `verification_method`, or `{\"Email\"}` when neither is sent. See **Verification & Notification Methods** for the full pairing table."
}
},
"additionalProperties": false
},
"minItems": 1
},
"expires_at": {
"type": "string",
"format": "date-time",
"description": "ISO 8601; default is no expiration. Must be at least one hour in the future."
},
"document_id": {
"type": "string",
"minLength": 1,
"description": "Document ID."
},
"estimate_only": {
"type": "boolean",
"description": "Preview cost and balances without creating an assignment or notifying anyone."
},
"copy_receivers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Signer IDs that only receive a copy."
}
},
"additionalProperties": false
}