Assinafy

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['action'], 'properties': {'action': {'enum': ['list'], 'type': 'string'}, 'account_id': {'type': 'string', 'minLength': 1, 'description': 'Authorized workspace; discovered from OAuth when omitted.'}, 'include_inactive': {'type': 'boolean', 'description': 'Include inactive field definitions.'}, 'include_standard': {'type': 'boolean', 'description': 'Include standard field types (signature, initial, signatureDate).'}}, 'description': 'List the field definitions of a workspace.\n\nWhen `include_standard` is enabled, records of type `signature`, `initial` and `signatureDate` are also returned.', 'additionalProperties': False}, {'type': 'object', 'required': ['field_id', 'action'], 'properties': {'action': {'enum': ['get'], 'type': 'string'}, 'field_id': {'type': 'string', 'minLength': 1, 'description': 'The field ID.'}, 'account_id': {'type': 'string', 'minLength': 1, 'description': 'Authorized workspace; discovered from OAuth when omitted.'}}, 'description': 'Retrieve a single field definition.', 'additionalProperties': False}, {'type': 'object', 'required': ['values', 'action'], 'properties': {'action': {'enum': ['validate'], 'type': 'string'}, 'values': {'type': 'array', 'items': {'type': 'object', 'required': ['field_id', 'value'], 'properties': {'value': {'description': 'The input value to validate.'}, 'field_id': {'type': 'string', 'description': 'The field definition ID.'}}, 'additionalProperties': False}, 'description': 'Field/value pairs to validate; sent to Assinafy as the JSON request array.'}, 'account_id': {'type': 'string', 'minLength': 1, 'description': 'Authorized workspace; discovered from OAuth when omitted.'}}, 'description': 'Validate one or more input values against existing field definitions without creating a document or requesting signatures. Supply field/value pairs in values; the server sends the documented JSON array.', 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['list', 'get', 'validate'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'required': ['document_id'], 'properties': {'document_id': {'type': 'string', 'description': 'unique document ID to delete'}}, 'additionalProperties': False}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['document_id', 'action'], 'properties': {'action': {'enum': ['artifact'], 'type': 'string'}, 'artifact': {'type': 'string', 'description': 'original (default), certificated, certificate-page, pades, or bundle'}, 'document_id': {'type': 'string', 'description': 'unique document ID'}}, 'description': 'Download a document artifact as base64.', 'additionalProperties': False}, {'type': 'object', 'required': ['document_id', 'page_id', 'action'], 'properties': {'action': {'enum': ['page'], 'type': 'string'}, 'page_id': {'type': 'string', 'minLength': 1, 'description': 'The page ID.'}, 'document_id': {'type': 'string', 'minLength': 1, 'description': 'Document ID.'}}, 'description': 'Download the rendered image of a specific document page.', 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['artifact', 'page'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['action'], 'properties': {'page': {'type': 'integer', 'description': 'page number (1-based)'}, 'sort': {'type': 'string', 'description': 'name or updated_at; prefix with - for descending'}, 'action': {'enum': ['list'], 'type': 'string'}, 'search': {'type': 'string', 'description': 'partial match on document name or signer'}, 'status': {'type': 'string', 'description': 'document status filter'}, 'per_page': {'type': 'integer', 'description': 'number of results per page (max 100)'}, 'account_id': {'type': 'string', 'description': 'account ID; uses request routing if omitted'}}, 'description': 'Search workspace documents with pagination and filters.', 'additionalProperties': False}, {'type': 'object', 'required': ['document_id', 'action'], 'properties': {'action': {'enum': ['get'], 'type': 'string'}, 'document_id': {'type': 'string', 'description': 'unique document ID'}}, 'description': 'Inspect one known document, its assignment, signers and artifacts.', 'additionalProperties': False}, {'type': 'object', 'required': ['document_id', 'action'], 'properties': {'action': {'enum': ['activities'], 'type': 'string'}, 'document_id': {'type': 'string', 'minLength': 1, 'description': 'Document ID.'}}, 'description': 'List the activities recorded for a document. Each entry carries an event-specific `payload` snapshot (keys vary per event) and the request `origin` (`ip`, `user-agent`).', 'additionalProperties': False}, {'type': 'object', 'required': ['document_id', 'assignment_id', 'action'], 'properties': {'action': {'enum': ['notifications'], 'type': 'string'}, 'document_id': {'type': 'string', 'minLength': 1, 'description': 'Document ID.'}, 'assignment_id': {'type': 'string', 'minLength': 1, 'description': 'The assignment ID.'}}, 'description': 'List all WhatsApp notification messages sent for an assignment. The response includes the rendered template text split into `header`, `body` and `buttons` — exactly what the signer would see. In sandbox/stage, WhatsApp messages are simulated (no real delivery) and button URLs include access/verification codes you can use to simulate the signing flow. Treat returned signing links and verification codes as sensitive; never use them to sign for another person.', 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['list', 'get', 'activities', 'notifications'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['action'], 'properties': {'page': {'type': 'integer', 'minimum': 1, 'description': 'Page number.'}, 'action': {'enum': ['list'], 'type': 'string'}, 'search': {'type': 'string', 'description': 'Filter by full_name or email.'}, 'per_page': {'type': 'integer', 'maximum': 100, 'minimum': 1, 'description': 'Records per page (max 100).'}, 'account_id': {'type': 'string', 'minLength': 1, 'description': 'Authorized workspace; discovered from OAuth when omitted.'}}, 'description': 'List the signers of a workspace.', 'additionalProperties': False}, {'type': 'object', 'required': ['signer_id', 'action'], 'properties': {'action': {'enum': ['get'], 'type': 'string'}, 'signer_id': {'type': 'string', 'minLength': 1, 'description': 'The signer ID.'}, 'account_id': {'type': 'string', 'minLength': 1, 'description': 'Authorized workspace; discovered from OAuth when omitted.'}}, 'description': "Retrieve a signer's information.", 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['list', 'get'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['action'], 'properties': {'page': {'type': 'integer', 'description': 'page number (1-based)'}, 'action': {'enum': ['list'], 'type': 'string'}, 'search': {'type': 'string', 'description': 'filter templates by name'}, 'per_page': {'type': 'integer', 'description': 'results per page'}, 'account_id': {'type': 'string', 'description': 'account ID; uses default if omitted'}}, 'description': 'List saved templates with roles and field placements.', 'additionalProperties': False}, {'type': 'object', 'required': ['template_id', 'action'], 'properties': {'action': {'enum': ['get'], 'type': 'string'}, 'account_id': {'type': 'string', 'description': 'account ID; uses default if omitted'}, 'template_id': {'type': 'string', 'description': 'unique template ID'}}, 'description': 'Get one template; this compatibility route is absent from the public API specification.', 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['list', 'get'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['document_id', 'assignment_id', 'signer_id', 'action'], 'properties': {'action': {'enum': ['resend'], 'type': 'string'}, 'signer_id': {'type': 'string', 'description': 'unique signer ID to notify'}, 'document_id': {'type': 'string', 'description': 'unique document ID'}, 'assignment_id': {'type': 'string', 'description': 'unique assignment ID'}}, 'description': 'Resend the invitation to a specific signer; requires authorization for the reminder.', 'additionalProperties': False}, {'type': 'object', 'required': ['document_id', 'assignment_id', 'expires_at', 'action'], 'properties': {'action': {'enum': ['set_expiration'], 'type': 'string'}, 'expires_at': {'type': 'string', 'description': 'new expiry timestamp in RFC 3339 format'}, 'document_id': {'type': 'string', 'description': 'unique document ID'}, 'assignment_id': {'type': 'string', 'description': 'unique assignment ID'}}, 'description': 'Change the expiration of an existing assignment.', 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['resend', 'set_expiration'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['file_name', 'file_base64', 'action'], 'properties': {'action': {'enum': ['upload'], 'type': 'string'}, 'file_name': {'type': 'string', 'description': 'PDF filename including .pdf'}, 'account_id': {'type': 'string', 'description': 'authorized workspace; discovered through OAuth when omitted'}, 'file_base64': {'type': 'string', 'description': 'base64 PDF bytes, at most 25 MiB decoded'}}, 'description': 'Upload a PDF without sending invitations. Keep its document ID.', 'additionalProperties': False}, {'type': 'object', 'required': ['name', 'document_id', 'action'], 'properties': {'name': {'type': 'string', 'maxLength': 255, 'minLength': 1}, 'action': {'enum': ['rename'], 'type': 'string'}, 'document_id': {'type': 'string', 'minLength': 1, 'description': 'Document ID.'}}, 'description': "Update a document's name. Only allowed before any assignment is created (i.e. while the document is in `uploaded` or `metadata_ready` status and has no signers yet); once the signature process has started or the document is certificated, the name is locked. The name is normalized: diacritics are removed and unsupported characters are replaced with dashes.", 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['upload', 'rename'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['file_name', 'file_base64', 'signers', 'action'], 'properties': {'action': {'enum': ['from_pdf'], 'type': 'string'}, 'message': {'type': 'string', 'description': 'invitation message shown to signers'}, 'signers': {'type': ['null', 'array'], 'items': {'type': 'object', 'required': ['full_name', 'email'], 'properties': {'email': {'type': 'string', 'description': "signer's email address; existing exact matches are reused"}, 'full_name': {'type': 'string', 'description': "signer's full name"}}, 'additionalProperties': False}, 'description': 'one or more signers to create or reuse and request signatures from'}, 'file_name': {'type': 'string', 'description': 'PDF filename including the .pdf extension'}, 'poll_secs': {'type': 'integer', 'description': 'polling interval in seconds (default 2; cannot exceed max_wait_secs)'}, 'account_id': {'type': 'string', 'description': 'account ID; uses the request or server default if omitted'}, 'expires_at': {'type': 'string', 'description': 'assignment expiry timestamp in RFC 3339 format'}, 'file_base64': {'type': 'string', 'description': 'base64-encoded PDF bytes (max 25 MB decoded)'}, 'max_wait_secs': {'type': 'integer', 'description': 'maximum seconds to wait for PDF processing (default 30; max 600)'}}, 'description': 'New PDF: provide file_name, file_base64 and signers by full_name/email. Creates a virtual assignment with Email verification and notification.', 'additionalProperties': False}, {'type': 'object', 'allOf': [{'if': {'required': ['method'], 'properties': {'method': {'const': 'collect'}}}, 'then': {'required': ['entries'], 'properties': {'entries': {'minItems': 1}}}}], 'required': ['method', 'signers', 'document_id', 'action'], 'properties': {'action': {'enum': ['from_document'], 'type': 'string'}, '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', 'required': ['id'], 'properties': {'id': {'type': 'string'}, 'step': {'type': 'integer'}, 'verification_method': {'enum': ['Email', 'Whatsapp', 'DigitalCertificate'], 'type': 'string', '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 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': {'type': 'array', 'items': {'enum': ['Email', 'Whatsapp'], 'type': 'string'}, 'description': '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"}`.'}}, 'additionalProperties': False}, 'minItems': 1}, 'expires_at': {'type': 'string', 'format': 'date-time', 'description': 'ISO 8601; default is no expiration.'}, 'document_id': {'type': 'string', 'minLength': 1, 'description': 'Document ID.'}, 'copy_receivers': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Signer IDs that only receive a copy.'}}, 'description': 'Request signatures on a document. Use `method: virtual` to sign without input fields, or `method: collect` to place input fields on specific pages.\n\nFor **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).\n\n`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. Obtain signer IDs from find_signers/save_signer and page IDs from find_documents action get. This sends signing invitations.', 'additionalProperties': False}, {'type': 'object', 'required': ['template_id', 'signers', 'action'], 'properties': {'name': {'type': 'string', 'description': 'custom document name'}, 'tags': {'type': ['null', 'array'], 'items': {'type': 'string'}, 'description': "tag names, merged with the template's defaults"}, 'action': {'enum': ['from_template'], 'type': 'string'}, 'message': {'type': 'string', 'description': 'signing invitation message'}, 'signers': {'type': ['null', 'array'], 'items': {'type': 'object', 'required': ['role_id'], 'properties': {'id': {'type': 'string', 'description': 'existing signer ID; use instead of full_name and email'}, 'step': {'type': ['null', 'integer'], 'description': 'signing order, contiguous from 1; all signers must set it if any does'}, 'email': {'type': 'string', 'description': "signer's email address, required when id is omitted; existing exact matches are reused"}, 'role_id': {'type': 'string', 'description': 'template role ID'}, 'full_name': {'type': 'string', 'description': "signer's full name; required when id is omitted"}, 'verification_method': {'type': 'string', 'description': 'Email (default), Whatsapp, or DigitalCertificate'}, 'notification_methods': {'type': ['null', 'array'], 'items': {'type': 'string'}, 'description': 'at most one channel: Email or Whatsapp; inferred from verification_method when omitted'}}, 'additionalProperties': False}, 'description': 'one signer per template role, each by ID or by name and email'}, 'account_id': {'type': 'string', 'description': 'account ID; uses request routing if omitted'}, 'expires_at': {'type': 'string', 'description': 'assignment expiry in RFC 3339 format'}, 'template_id': {'type': 'string', 'description': 'template ID'}, 'editor_fields': {'type': ['null', 'array'], 'items': {'type': 'object', 'required': ['field_id', 'value'], 'properties': {'value': {'type': 'string', 'description': 'value to bake into the generated document'}, 'field_id': {'type': 'string', 'description': 'template editor field ID'}}, 'additionalProperties': False}, 'description': 'template editor field values'}}, 'description': 'Saved template: provide template_id and one signer per role, by id or full_name/email. Use field_id/string-value pairs in editor_fields, after check_fields validation.', 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['from_pdf', 'from_document', 'from_template'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'oneOf': [{'type': 'object', 'required': ['full_name', 'action'], 'properties': {'email': {'type': 'string', 'format': 'email'}, 'action': {'enum': ['create'], 'type': 'string'}, 'full_name': {'type': 'string', 'minLength': 1}, 'account_id': {'type': 'string', 'minLength': 1, 'description': 'Authorized workspace; discovered from OAuth when omitted.'}, 'whatsapp_phone_number': {'type': 'string', 'description': 'E.164; normalized on save.'}}, 'description': 'Create a signer in the workspace.', 'additionalProperties': False}, {'type': 'object', 'anyOf': [{'required': ['full_name']}, {'required': ['email']}, {'required': ['whatsapp_phone_number']}, {'required': ['government_id']}], 'required': ['signer_id', 'action'], 'properties': {'email': {'type': 'string', 'format': 'email'}, 'action': {'enum': ['update'], 'type': 'string'}, 'full_name': {'type': 'string', 'minLength': 1}, 'signer_id': {'type': 'string', 'minLength': 1, 'description': 'The signer ID.'}, 'account_id': {'type': 'string', 'minLength': 1, 'description': 'Authorized workspace; discovered from OAuth when omitted.'}, 'government_id': {'type': 'string', 'description': "Signer's CPF/CNPJ; digits only on save."}, 'whatsapp_phone_number': {'type': 'string', 'description': 'E.164; normalized on save.'}}, 'description': "Update a signer's information.\n\n**Verification integrity:** `email` / `whatsapp_phone_number` cannot be changed while the signer has verified that channel on an in-flight (not yet certificated) document — the response is `400` naming the offending document(s). Already-certificated documents do not block updates. Changing a channel that has *unverified* in-flight requests rotates their access/verification codes (invalidating previously sent links/OTPs); use the resend endpoint to redeliver. `full_name` can always be updated.", 'additionalProperties': False}], 'required': ['action'], 'properties': {'action': {'enum': ['create', 'update'], 'type': 'string', 'description': 'Choose exactly one action; supply only its arguments.'}}}

{'type': 'object', 'required': ['hash'], 'properties': {'hash': {'type': 'string', 'description': 'SHA-1 signature hash of the signed document'}}, 'additionalProperties': False}