Document field reference

This page lists the fields you can send in POST /api/documents: the participant data, the options of each participant and the document options. To create a document step by step, see Create documents.

The participant (user)

Field	Description
name	Participant's name, up to 200 characters.
email	Participant's e-mail.
identifier	Participant's main identifier, for example the CPF.
identifierType	Type of the main identifier (see the table below).
identifiers	List of identifiers, each with type and value. Only applies when the instance allows multiple identifiers per user.
phone	Mobile phone in international format, for example +55 11 91234-5678. The Signer uses the phone only if the user does not exist yet: it does not change the phone of an existing user.

The identifier types (identifierType and identifiers[].type) are:

Type	Document
Cpf	CPF (Brazil)
EcuadorBceId	Ecuador identifier
ParaguayCedulaIdentidad	Cédula de Identidad (Paraguay)
ParaguayRuc	RUC (Paraguay)
ParaguayPassport	Paraguayan passport
Passport	Passport from any country
Ssn, Itin, Ein	SSN, ITIN and EIN (United States). Available from version 3.0.0.

The instance defines which types it accepts. To learn how the Signer uses the identifier and the e-mail to find the user, and how multiple identifiers and foreign signers work, see Participant identification. To register identifiers for an existing user, see Contacts and identifiers.

Participant options

Besides type, step and user, each flowActions item accepts these options:

Field	Description
title	Participant's title on the document, for example "Party" or "Witness".
disableRefusal	If true, the participant cannot refuse the document. The screen does not show the refusal option, and the refusal API rejects the request. The default is false.
notificationLanguage	Language of this participant's notifications: Pt, En or Es. See Notifications.
signatureInitialsMode	Participant's initials: None (no initials), Optional or Required.
requiredCertificateTypeToSign	Certificate type the participant must use: A1, A2, A3, A4, S1, S2, S3, S4, T3 or T4.
requiredCertificateHolderTypeToSign	Certificate holder: Individual (a person, for example e-CPF) or Company (a legal entity, for example e-CNPJ).
requiredCompanyIdentifier	CNPJ that the company certificate must have.
requireCompanyCertificate	Obsolete. Use requiredCertificateHolderTypeToSign with Company.
allowIdrcSignature	If true, the participant can choose between an IdRC signature and a certificate signature. Only applies if the instance has IdRC enabled.

The options below only apply when allowElectronicSignature is true. Each one adds a check before the electronic signature:

Field	The participant must
requireSmsAuthenticationToSignElectronically	Enter a code sent by SMS.
requireWhatsappAuthenticationToSignElectronically	Enter a code sent by WhatsApp.
requireAuthenticatorAppToSignElectronically	Enter a one-time password (OTP) from an authenticator app.
requireSelfieAuthenticationToSignElectronically	Take a selfie.
requireDatavalidAuthenticationToSignElectronically	Take a selfie, which SERPRO's Datavalid validates.
requirePixAuthenticationToSignElectronically	Pay a Pix.
requireLivenessAuthenticationToSignElectronically	Take a liveness test.
requireIdScanAuthenticationToSignElectronically	Photograph an ID document with a photo.
disableEmailAuthenticationToSignElectronically	Not enter the code sent by e-mail. Only accepted if SMS or WhatsApp is also required.

Document options

These optional fields of POST /api/documents apply to all documents in the request:

Field	Description
notifiedEmailsData	List of e-mails that receive the concluded-document notice. Each item has email and notificationLanguage (Pt, En or Es). Without a language, the Signer uses the instance's default language. Use this field instead of notifiedEmails, which is obsolete.
timestampEnabled	Overrides the organization's timestamp setting for this document. true applies a timestamp to all signatures, and false to none. Without the field, the organization's setting applies. If the instance has no timestamper, document creation is rejected.
signerPositioningEnabled, automaticSignaturePositioning	See Signer positioning of the signature.
overrides	Bypasses, for this request only, an organization requirement: disableTagRequirement (required tag), disableRegisteredTagLabelsRequirement (registered tags only) and disableRequireFolderOnDocumentCreation (required folder). Only an API key can enable these options. Any other kind of user gets the AgentIsNotApplication error. See the requirements in Organization settings through the API.
accessValidationType	Who can look up the document by its validation code. Only takes effect if the instance enables access validation (see Signer settings). The values are in the table below. Without the field, the instance default applies.

The accessValidationType values are:

Value	Who can look up the document
UserIdentifier	Whoever enters the identifier (for example the CPF) of a participant of the document.
Login	Any user signed in to the Signer.
ParticipateInOrganization	A user with a role in the document's organization.
HasAccessToDocument	A user with access to the document in the Signer, or the document's creator if they are still a member of the organization.
None	Anyone, even if the instance requires validation on every document.