search
HomeAppAPI Keys

Creating a document

To create a document/send a document for signature

Creating documents differs slightly from other mutations because it involves uploading a file. First, we need to write the mutation:

mutation CreateDocumentMutation(
  $document: DocumentInput!, # Definition of the $document variable
  $signers: [SignerInput!]!, # $signers and $file, with its respective
  $file: Upload!             # types. (The "!" indicate that are
) {                          # mandatory parameters)      
  createDocument(
    document: $document,     # Pass the variable values to the mutation parameters
    signers: $signers,       # 
    file: $file,             #
    organization_id: 123,    # OPTIONAL: Creates in other user organizations, otherwise uses the current one
    folder_id: "a1b2c3"      # OPtIONAL: Creates archived in a folder
  ) {
    id
    name
    refusable
    sortable
    created_at
    signatures {
      public_id
      name
      email
      created_at
      action { name }
      link { short_link }
      user { id name email }
    }
  }
}

Next, we need the values of the variables defined in the mutation in a JSON:

Notice that no value has been provided for the $file variable? That's because since the file is being uploaded, the request needs to be sent as multipart/form-data, so the file must be handled a bit differently. You can do this directly in Altairarrow-up-right:

circle-exclamation

If you're unsure how document submission works for your integration, this repository provides more information and examples on how to handle the upload: https://github.com/jaydenseric/graphql-multipart-request-specarrow-up-right.

hashtag
Creating documents on Sandbox

Our API also supports sending test documents, which do not consume document credits, making integration easier for those who have not yet acquired a plan with unlimited documents. To learn how to do this, visit our sandbox page.

hashtag
More options:

hashtag
Additional Validations

You can implement additional validations in your documents. These configurations must be included in the security_verifications list of the signer object, using the type field to define the desired challenge modality. In addition to the types, fields such as verify_phone and cpf assist in the delivery of security codes and in the precise identification of the signer.

Field / Verification Type
How it works

verify_phone

The signer must validate a mobile number through a code sent via SMS. You can pre-fill the number or leave it blank so the signer can provide it themselves.

cpf

Configuration that ensures only the signer with the specified CPF can sign the document. If defined, the system forces the entry or validation of this data in the signer's account

MANUAL

The signer will attach a photo ID and take a selfie. You or a member of your organization can then approve or reject the submitted documents and selfie

UPLOAD

The signer must attach the front and back of a photo ID using their smartphone or computer

LIVE

The signer will need to attach a photo ID, take a selfie with their smartphone, and perform a liveness check (video). The document photo will be automatically compared to the selfie to verify the degree of similarity

PF_FACIAL

The signer takes a selfie which is validated by SERPRO, comparing it to Brazilian government registration photos linked to the informed CPF

BIOMETRIC_AND_TEXT_EXTRACTION

The signer will need to photograph an ID document and take a selfie, the document photo will be compared with the selfie to determine the similarity score.

LIVENESS_AND_TEXT_EXTRACTION

The signer will need to perform a liveness check and photograph a photo ID. Document information will be automatically extracted and compared to verify the similarity score.

chevron-rightPositioning signature fields "positions"hashtag

As shown in the example above, to add signature fields when creating the document, you need to include the "positions" attribute.

The “x” value represents the horizontal position, ranging from 0% to 100%. The “y” value represents the vertical position, also ranging from 0% to 100%. The “z” value indicates the page number, starting at 1.

O "element" It's the type of signature "SIGNATURE": Signature "NAME": Signer's name "INITIALS": Initials "DATE": Signature date "CPF": Signer CPF

To know what positions to pass for x and y, you can create a sample document in the Autentique dashboard and retrieve the positions by fetching the document using "positions":

chevron-rightRequire SMS verification and/or photo document verification "security_verifications"hashtag

To require signers to verify via SMS and/or photo document, you need to add the "security_verifications" attribute to the signer for whom these verifications should be required. Remember to check in the dashboard for the cost of additional verification credits needed.

The "type" is the type of verification:

  • "SMS": SMS validation ("verify_phone" is optional and requires a specified phone number)

  • "MANUAL": Require a photo document (manual approval)

  • "UPLOAD": Require a photo document (photo document)

  • "LIVE": Require a photo document (document, selfie, and proof of life)

  • "PF_FACIAL": Require a photo document (SERPRO biometric verification)

  • "BIOMETRIC_AND_TEXT_EXTRACTION": Require a photo document (photo document and facematch)

While it's possible to have multiple verifications for the same signer, you can only choose one of the following options per signer: MANUAL, UPLOAD, LIVE, and PF_FACIAL.

When the types UPLOAD, LIVE, PF_FACIAL and BIOMETRIC_AND_TEXT_EXTRACTION are used, there is a default behavior where they are changed to MANUAL when the signer exceeds the maximum number of attempts in the document validation process. To disable this behavior, you must use the fallback_behavior parameter, which will flag the document as failed and automatically reject it.

chevron-rightCreate a document from a templatehashtag

There is no way in the API to directly use the panel templates to create documents. However, you can achieve something similar through your code:

  1. Create a fixed HTML template on your machine, marking the places with variables to be replaced by values. (e.g., "I, $NomeSignatario$, accept this contract")

  2. Programmatically duplicate this HTML and in the duplicate, replace the variable fields with the actual values. (e.g., $NomeSignatario$ → Jorge Silva)

  3. Send this HTML file with the replaced values to our API through the createDocument mutation, just like it works for other types of files.

chevron-rightExample of document creation with NodeJShashtag

If you use Postman, you can generate these examples from the Postman collection provided here in the documentation.

For this example, just replace the API token, the signer's email, and the file path.

chevron-rightExample of document creation with PHPhashtag

If you use Postman, you can generate these examples from the Postman collection provided here in the documentation documentation.

In this example, you just need to replace the API token, the signer's email, and the file path.

chevron-rightExample of document creation with Python3hashtag

If you use Postman, you can generate these examples from the Postman collection provided here in the documentation documentation.

In this example, you just need to replace the API token, the signer's email, and the file path.

chevron-rightExample of document creation with C#hashtag

If you use Postman, you can generate these examples from the Postman collection provided here in the documentation documentation.

In this example, you just need to replace the API token, the signer's email, and the file path.

circle-info

You can check what each of these parameters means directly in the full GraphQL API documentation, in the Docs menu of Altairarrow-up-right. If you're not sure how to do that, check out our tutorial on Using Altair.

file-download
19KB
Autentique v2.postman_collection.json
arrow-up-right-from-squareOpen
Para importar e usar no Postman
PreviousListing email templatesNextSending Documents via WhatsApp Flow

Last updated