When creating an envelope, the issuer must provide the following required fields:

initiative

Used to identify the issuer during the signing process. The initiative value must match the client_id from the integration that you obtained while requesting your Sovos credentials.

This field uses a UUID (Universally Unique Identifier) represented as a string of 32 hexadecimal digits, organized in five groups separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters (32 alphanumeric characters and four hyphens). Example: 97556bdf-65db-49fe-a674-ea9e4a16d65a.

personIndex

The position of the issuer in the persons list. This key must be included for identification and audit purposes, even when the issuer doesn't sign the documents.

nonce

"Number used once". A unique, random value created by the issuer to identify each signature process. It helps prevent duplicate envelope deliveries and add an extra layer of security to the signature process.

If you use a duplicate nonce, the system returns an error message. The issuer must create a new nonce for each envelope.

The value accepts up to 64 alphanumeric characters. Example: unique-nonce-value.

Example of an issuer object:

{
    "envelope": {
        "issuer": {
            "initiative": "97556bdf-65db-49fe-a674-ea9e4a16d65a",
            "personIndex": 0,
            "nonce": "unique-nonce-value"
        },
        "documents": ...,
        "persons": ...,
        "signatures": ...,
        "signatureProcessing": ...
    }
}

Example of a documents array including two files:

{
  "envelope": {
    "issuer": ...,
    "documents": [
      {
        "name": "contrato_12345.pdf",
        "mediaType": "application/pdf",
        "content": "base64-encoded-content"
      },
      {
        "name": "anexo_67890.pdf",
        "mediaType": "application/pdf",
        "content": "base64-encoded-content"
      }
    ],
    "persons": ...,
    "signatures": ...,
    "signatureProcessing": ...
  }
}

The required information for the persons object includes:

credential

The person's credential information:

• The certificate issuer's country code using the ISO 3166 Alpha-3 standard and ISO639-1 for language. Example: CHL-es. Accepted country values:

  • GLOBAL for a global issuer.

  • CHL for a Chilean issuer.

  • PER for a Peruvian issuer.

• The credential issuer identifier, as a union-type value. Allowed values are:

  • SRCEI for Chile.

  • RENIEC for Peru.

• The credential type. Allowed values:

  • RUN for Chile.

  • DNI for Peru.

• The subject as an identifier of the end user that the credential issuer defines. This is the credential type number, uniquely identifying the individual. Example: 12345678-5 for Chile.

CAUTION:

You can include a person without specifying all the keys, but any key that is declared with a null or undefined value will cause an error.

provided

The person's basic information, including strings for:

• Email.

• Full name in LASTNAME<LASTNAME<<FIRSTNAME<MIDDLENAME format, where single and double angle brackets are field separators.

• Phone number in E.164 format.

  Note:

  The E.164 format is an international standard for telephone numbers that follows the pattern of a maximum of 15 digits, with a + symbol, the two-number country code, the area code, and phone number. Example: +56912345678, for a Chilean phone number.

idToken

The ID token from the authentication process. It must be a valid JWT token, a digitally signed string that securely transmits user or system information. The server verifies the token to ensure authenticity and integrity.

Example of a persons array, with two signers:

{
"envelope": {
	"issuer": ...,
 	"documents": ...,
	"persons": [
  {
    "credential": {
      "country": "CHL",
      "issuer": "SRCEI",
      "type": "RUN",
      "subject": "12345678-5"
    },
    "provided": {
      "email": "signer1@email.com",
      "name": "PEREZ<GARCIA<<JUAN<JOSE",
      "phone": "+56911112222"
    },
    "idToken": "eyJraWQiOiJrZXkiLCJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  },
  {
    "credential": {
      "country": "CHL",
      "issuer": "SRCEI",
      "type": "RUN",
      "subject": "87654321-0"
    },
    "provided": {
      "email": "signer2@email.com",
      "name": "PEREZ<<MARIA",
      "phone": "+56933334444"
    },
    "idToken": "eyJraWQiOiJrZXkiLCJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
],
    "signatures": ...,
    "signatureProcessing": ...
}
}

The signature field is an array that contains multiple Signature objects. Each Signature object represents an individual signature within the document, linked to a document and a person through index keys.

documentIndex

Identifies the document to sign and must match a valid index in the 'documents' array, starting with 0 for the first one.

personIndex

Identifies the person who signs the document and must match a valid index in the 'persons' array, starting with 0 for the first one.

type

The types of signature used.

Allowed value: SIGNATURE_TYPE_AUTO.

signatureCustomization

An array that contains multiple objects for signature customization options. These objects define customizations for the signature, such as:

• appearance array includes additional fields to customize the appearance of the signature, such as signer's name, position, date, logo, and signature stamp style.

• positions array represents the location of a signature within the document through keys such as the page number and the X and Y coordinates. Set the position for each signature individually; it affects only that specific signature, not all signatures in the array.

Example of a signature array with two signatures:

{
    "envelope": {
        "issuer": ...,
        "documents": ...,
        "persons": ...,
        "signatures": [
            {
                "documentIndex": 0,
                "personIndex": 0,
                "type": "SIGNATURE_TYPE_AUTO",
                "signatureCustomization": [
                    {
                        "positions": [
                            {
                                "page": 1,
                                "x": 100,
                                "y": 100
                            }
                        ]
                    }
                ]
            },
            {
                "documentIndex": 1,
                "personIndex": 0,
                "type": "SIGNATURE_TYPE_AUTO",
                "signatureCustomization": [
                    {
                        "positions": [
                            {
                                "page": 2,
                                "x": 150,
                                "y": 250
                            }
                        ]
                    }
                ]
            }
        ],
        "signatureProcessing": ...
    }
}

An array that defines the order and indexes for signatures to ensure that the signatures are processed accurately and in the desired sequence.

order

Specifies how signatures are processed.

Allowed values:

• SIGNATURE_PROCESSING_ORDER_PARALLEL, all signatures can be processed at the same time.

• SIGNATURE_PROCESSING_ORDER_SEQUENTIAL, signatures must be processed one after another, in the order defined by the array.

signatureIndexes

Specifies the position for each signature in the 'signatures' array. Every signature in the signatures array must have its index listed in signatureIndexes.

Example of a signatureProcessing object, using parallel order:

{
    "envelope": {
        "issuer": ...,
        "documents": ...,
        "persons": ...,
        "signatures": ...,
        "signatureProcessing": {
            "order": "SIGNATURE_PROCESSING_ORDER_PARALLEL",
            "signatureIndexes": [0, 1]
        }
    }
}

Example of a signatureProcessing object, using sequential order. In the example, signature 1 is processed before signature 0.

{
    "envelope": {
        "issuer": ...,
        "documents": ...,
        "persons": ...,
        "signatures": ...,
        "signatureProcessing": {
            "order": "SIGNATURE_PROCESSING_ORDER_SEQUENTIAL",
            "signatureIndexes": [1, 0]
        }
    }
}