Skip to content

Web Services / V6 Integration API

Prerequisites

Prerequisites for the use of integration web services

To obtain authentication access to the Trust and Sign web services, you must complete the account creation process with * Namirial*.

In order to use the APIs exposed by Trust and Sign, a login/password pair is required. This information is provided in the document_product.pdf file sent by Namirial when a product is created. The login corresponds to the public ID and the password to the secret key.

The basic URLs of the integration services are as follows:

The following chapters describe the JSON API. As the product evolves, we may add undocumented fields in the returns. You should therefore not be too restrictive on the payloads.

Please note that the name of the keys is case sensitive. Mandatory fields are marked (*), other fields are optional.

Authentication

Basic" authentication is used here; it follows the [RFC1945] standard (http://tools.ietf.org/html/rfc1945). An HTTP header named AUTHORIZATION must be added to requests. This is of the form :

AUTHORIZATION = Basic base64(login:password)

The following code snippet can be used in Java to generate this header:

String header = "Basic " + Base64.getEncoder().encodeToString((login + ":" + password).getBytes(StandardCharsets.UTF_8));

For example, for a login "john123456" and a password "azerty" we get the following header is obtained:

AUTHORIZATION = Basic am9objEyMzQ1NjphemVydHk=

For some requests, it is also necessary to identify the user. For this purpose, a header named USER is used which corresponds to the identifier of a Trust and Sign* operator.

USER = 2e891756-cbbb-11e3-9d6a-57f4740d8223

Creating a customer file

** Request **

Content-Type: multipart/form-data
POST /v6/integration/client-files

Description of the "shares ".

  • workflowLabel (*): name of the workflow configured in the workflow administration interface. This string must be encoded in UTF-8 and not exceed 64 characters;

  • amount: amount of the file in text format example: 123.45.

  • documentToSign-{id}: binary data of the PDF documents that will be signed. The id value corresponds to the document identifier defined in Workflow. Only documents to be signed, or all documents can be sent (even those which, for reasons of inactivation reasons, will not be signed); in the first case, the modification of the profiles during an update of the file is not of the file is not possible because some documents might be missing. If the signature is deactivated for this pathway, this field should not be set. These documents can be omitted when the file is created, but in this case they will have to be defined before the file is created. in this case they will have to be defined before signing using the call to update documents;

  • documentTemplateFields-{id}*: a JSON containing information that can be inserted into PDF templates. These templates are PDFs containing form fields and are inserted into the path configuration. Note that the use of this functionality and the Note that the use of this functionality and signature fields are incompatible. These documents can be omitted when creating the file, but in this case they will have to be defined before signing using the document update call. This JSON contains key/value pairs with key = name of the field in the PDF form. The values differ depending on the type of field:

    • text: a simple text (can contain variables)
    • checkbox: a boolean (true to check / false to uncheck)
    • choice (drop-down list, group of radio buttons, etc.): the name of the choice
{
    "name": "${signer.firstName} ${signer.lastName?upper}",
    "social_security_number": "${externalInfo.social_security_number}",
    "status": "pacse",
    "receive_promotional_offers": false
}
  • appendix-{id}: binary data of the appendix files that will be saved with the rest of the documents (archive and evidence file). The id value must be a unique identifier containing only ASCII characters and numbers (no spaces). The form-data parameter filename is mandatory

Example:

Content-Disposition: form-data; name="appendix-doc1"; filename="doc1.pdf"
Content-Type: application/pdf

binary data

  • externalId: external identifier used to identify (uniquely) a file. For the same product, two files cannot have the same externalId, otherwise For the same product, two folders cannot have the same externalId, otherwise the error 1047 will be returned. This value must not exceed 36 characters;

  • groupLabel: Label of the group within which the folder is to be added. If no value is entered, the folder is added to the default group. If the group label does not exist, error 1062 will be raised.

  • externalInfo: additional data from the file. This value must be in the form of a JSON encoded in UTF-8. It is a list of keys/values to add information to a folder. Each value must be a string encoded in in UTF-8. For example, the file identifier in the external external information system;

    • key: 128 characters maximum
    • value*: 1023 characters maximum
{
    "clientId": "123456789",
    "my_key": "my_value"
}
  • legalEntity: data of the legal entity as a JSON encoded in UTF-8. This field must only be present if the course supports legal entities. This JSON has the keys
    • legalName (*) for the company name;
    • companyId (*) for the identifier (SIREN or SIRET) of the legal entity;
    • iban: the iban to be compared with the document that the participant will provide;
    • postalAddress: the postal address
      • address1 (*): the first line of the postal address of the legal entity
      • address2 : the second line of the postal address
      • address3: the third line of the postal address
      • city (*): the city of the postal address Authorised characters: numbers, unicode letters, apostrophes, commas, hyphens, full stops and spaces. Characters not allowed: special characters:! @ # $ % & * ( ) _ + = { } [ ] | ; : " < > ? / mathematical symbols: / = < > ^ % | punctuation characters, diacritical characters.
      • postalCode (*): the postal code of the city

List of accepted characters for the legalName field: [a-Z][0-9]éèàùçâêûîäëïüö£!#%&'()*-./:;=?@[]^_` {|}\"€<>+\

{
    "legalName": "My company",
    "companyId": "123456789",
    "postalAddress": {
        "address1": "123 rue Victor Hugo",
        "postalCode": "75000",
        "city": "Paris"
    }
}
  • entityStamps: the stamps (organism signature) to be applied on the contracts. This parameter is only useful if the signature is activated in the path. If this field is not present, all stamps defined in the path are applied; otherwise only those defined here will be applied. This parameter is a JSON array with the following keys:
    • id: the identifier of the contract receiving the stamp (defined in the path interface)
    • visualsIds: array of visuals identifiers to be applied
[
    {
        "id": "contract-1",
        "visualsIds": [
            "visual-01",
            "visual-02"
        ]
    }
]
  • participants*: the participants' information in the form of a JSON array encoded in UTF-8. The following keys must be used:
    • type (*): identifies a participant as configured in the course configuration interface;
    • state: the state of each participant
    • civility (*) : the civility of the participant (MR, MRS, MISS or UNKNOWN);
    • firstName (*) : the participant's first name encoded in UTF-8, containing a maximum of 64 characters (all letters of the different alphabets as well as numbers and joins are accepted, special characters are not allowed);
    • lastName (*) : the participant's last name encoded in UTF-8, containing a maximum of 64 characters (all letters of the different alphabets as well as numbers and joins are accepted, special characters are not allowed) ;
    • email (*): the participant's e-mail address encoded in UTF-8, not exceeding 128 characters and having to standard rfc2822;
    • mobilePhone: the participant's mobile phone number (may start with +33). If the signature is present in the course, this field becomes mandatory. The file will not be created if the phone format is not valid;
    • birthName: the participant's birth name if it is different from his/her family name (because of a marriage for example). This string must be encoded in UTF-8, containing a maximum of 64 characters (all letters of the different alphabets as well as numbers and joins are accepted, special characters are not allowed) ;
    • birthPlace: the place of birth of the participant, as it appears on his/her national identity card. This field contains the name of the city in capital letters (without department or country number, without abbreviations ST/SAINT, etc.); it may contain a district number for large cities, separated by a space and followed by the letter E. Other characters are not allowed. Examples: PARIS, MARSEILLE 2E.
    • profiles: list of profiles to be used as a JSONArray. Each value must be a string. The size must not exceed 256 characters.
    • iban : the iban to be compared with the document the participant will provide
    • postalAddress : the postal address of the participant
      • address1 (*) : the first line of the signer's postal address encoded in UTF-8 and not exceeding 128 characters. If this If this field is provided, the city and postalCode fields must also be provided;
      • address2: second line of the signatory's postal address encoded in UTF-8 and not exceeding 128 characters.
      • address3: the third line of the signatory's postal address encoded in UTF-8 and not exceeding 128 characters.
      • city (*): The signatory's postal city encoded in UTF-8, not to exceed 64 characters. Authorised characters: numbers, unicode letters, apostrophes, commas, hyphens, full stops and spaces. Characters not allowed: special characters:! @ # $ % & * ( ) _ + = { } [ ] | ; : " < > ? / mathematical symbols: / = < > ^ % | punctuation characters, diacritical characters.
      • postalCode (*): The signatory's postal code encoded in UTF-8 and containing only numbers.
      • countryCode*: The country code of the signatory encoded in UTF-8 and respecting the [ISO3166-1] standard (https://www.iso.org/fr/iso-3166-country-codes.html).
    • phone: the signatory's fixed telephone number in the format +33666666666 or 0666666666.
    • birthDate: the date of birth of the signatory in YYYY-MM-DD (ISO8601) format.
    • signatures: the list of documents that the participant must sign (This parameter is deprecated since version 21.2 and it is advised to use the documentsToSign and documentsToVisualize parameters):
      • documentToSignId (*) : the identifier of the document to be signed (as defined in the path configuration interface)
      • visualIds (*) : the identifiers of the visual signatures to be used in the document. If the table is empty, the contract will not be signed (only viewed by the user). At least one of the defined contracts must have a link to a visual
    • documentsToSign: the list of documents that the participant must sign
      • id (*) the identifier of the document to be signed (as defined in the course configuration interface)
      • visualIds (*): the identifiers of the visual signatures to be used in the document. If this table is not present or if it is empty then a signature without visuals will be applied. At least one of the defined contracts must have a link to a visual
    • documentsToVisualize : the list of documents that will be visualized, but not signed by the participant (no signature)
      • id (*) the identifier of the document to be visualized (as defined in the course configuration interface)
    • legalAgent : boolean indicating that the participant is one of the legal entity's agents. This field is only useful if the legal entity is activated in the path
    • oneccToken: One Click Contract Token of the participant's reference file
    • externalId: External identifier of the participant
[
    {
        "type": "sign",
        "state": "PENDING",
        "civility": "MR",
        "firstName": "John",
        "lastName": "Doe",
        "email": "j.doe@example.com",
        "mobilePhone": "0606060606",
        "birthDate": "1970-02-12",
        "birthPlace": "MACON",
        "oneccToken": "20190920_eWticz85PZRHhB8gexjWYkK77bXs0f",
        "externalId": "idExternal",
        "postalAddress": {
            "address1": "123 rue Victor Hugo",
            "postalCode": "75000",
            "city": "Paris"
        },
        "documentsToSign": [
            {
                "id": "my-contract3",
                "visualIds": [
                    "visual-01",
                    "visual-02"
                ]
            }
        ],
        "documentsToVisualize": [
            {
                "id": "my-contract4"
            }
        ]
    }
]

** Back **

A JSON object containing the following information:

  • creationDate: the date of creation of the file ;
  • externalInfo: JSON containing the external information defined when the file was created
{
    "clientId": "123456789",
    "my_key": "my_value"
}
  • externalId: external identifier given when the file is created
  • uuid: folder identifier
  • state: the state of the file (INITIALIZED or PENDING);
  • workflowLabel: the label of the workflow used for the file;
  • archivingState: the archiving state of the file. The following values are possible:
    • NO_ARCHIVING: archiving is not activated for this file
    • ARCHIVED: the file has been archived
    • NOT_YET_ARCHIVED: the file is not yet archived
    • ARCHIVING_IS_SCHEDULED: the file is not yet archived, archiving is scheduled
    • NOT_ARCHIVED: the file has not been archived because it has been rejected or the archiving deadline has passed
  • participants: the information of the participants in the form of a JSON table
    • uuid: participant identifier
    • accessToken: the token used to identify the file during calls to /api
    • type: the type of the participant as defined in the course configuration interface;
    • civility: the civility (MR, MRS, MISS or UNKNOWN);
    • email: the email address of the signatory;
    • birthName: the birth name of the signatory;
    • postalAddress: postal address of the signatory. This is a JSON containing the fields postalAddress1, postalAddress2, postalAddress3, postalCode, city and countryCode;
    • mobilePhone: mobile phone number;
    • phone: landline telephone number;
    • birthDate: the date of birth of the signatory;
    • downloadDocumentsBeforeSignature: All documents before signing have been uploaded (not present if Force upload of documents before signing = No)
    • downloadSignedDocuments : All signed documents have been uploaded (not present if Forced upload of documents after signing = No)
  • signDocuments : the list of documents that can be signed
    • id: the unique identifier of the contract (defined in the path configuration interface). The document can be downloaded using this identifier ;
    • label: the name of the document
  • group: the group of the file
    • uuid: the group identifier
    • label: the group label
    • defaultGroup : true if it is the default group of the company
{
    "externalInfo": {
        "my_key": "my_value"
    },
    "externalId": "myExternalId00003",
    "workflowLabel": "workflow-simple",
    "state": "PENDING",
    "id": 10002,
    "creationDate": "2016-09-05T09:50:30Z",
    "uuid": "28af2a55-e815-4725-acdf-2ede49cd6933",
    "recoverableDocumentTypes": [
        "ID_CARD"
    ],
    "participants": [
        {
            "uuid": "546875455-e815-4725-acd",
            "type": "sign",
            "firstName": "John",
            "lastName": "Doe",
            "civility": "MR",
            "mobilePhone": "0606060606",
            "profiles": [
                "single",
                "otherprofile"
            ],
            "birthDate": "1987-03-16",
            "email": "john@doe.com",
            "accessToken": "20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
            "externalId": "idExternal",
            "downloadDocumentsBeforeSignature": true,
            "downloadSignedDocuments": false
        }
    ],
    "signDocuments": [
        {
            "id": "contract",
            "label": "My contract"
        }
    ],
    "group": {
        "uuid": "8cb80ab2-a689-4568-ab85-07c33203842b",
        "label": "DEFAULT",
        "defaultGroup": "true"
    }
}

Updating a participant's information

A participant's information can be updated. The request must contain all the information of the participant, not just the information that is to be updated. Signed records can no longer be modified.

Caution If you have submitted documents before signing, and consistency errors are found, these checks will remain in error.

Caution Participant type cannot be updated.

** Request **

Content-Type: multipart/form-data
PUT /v6/integration/client-files/{clientFileUuid}/participants/{participantUuid}

Description of the "shares ".

  • participant*: the participant's information in the form of a JSON encoded in UTF-8. The following keys must be used:
    • type (*) : to identify a participant : identifier defined in the course configuration interface (this element cannot be updated) ;
    • civility (*): the civility of the participant (MR, MRS, MISS or UNKNOWN);
    • firstName (*) : the first name of the participant encoded in UTF-8, containing a maximum of 64 characters;
    • lastName (*) : the last name of the participant encoded in UTF-8, containing a maximum of 64 characters;
    • email (*) : the participant's email address encoded in UTF-8, not exceeding 128 characters and having to comply with the standard rfc2822;
    • mobilePhone: the participant's mobile phone number (may start with +33). If the signature is present in the course, this field becomes mandatory;
    • birthName: the participant's birth name if it is different from his/her family name (because of a marriage for example). This string must be encoded in UTF-8, containing a maximum of 64 characters;
    • birthPlace: the place of birth of the participant, as it appears on his/her national identity card. This field contains the name of the city in capital letters (without department or country number, without abbreviations ST/SAINT, etc.); it may contain a district number for large cities, separated by a space and followed by the letter E. Other characters are not allowed. Examples: PARIS, MARSEILLE 2E.
    • profiles: list of profiles to be used as a JSONArray. Each value must be a string. The size must not exceed 256 characters. If the participant has already signed his contracts, it is no longer possible to modify the profiles. Note that it is not possible to delete a profile, unless it is associated with one or more consent clauses. Other types of profiles can only be added. It is advisable not to add a profile to a participant when the file is in the status to be validated, released, accepted or rejected.
    • iban: the iban to be compared with the document that the participant will provide
    • postalAddress: the participant's postal address
      • address1: the first line of the signatory's postal address encoded in UTF-8 and not to exceed 128 characters. If this field is provided, the city and postalCode fields must also be provided;
      • address2: second line of the signatory's postal address encoded in UTF-8 and not exceeding 128 characters.
      • address3: the third line of the signatory's postal address encoded in UTF-8 and not exceeding 128 characters.
      • city: The signatory's postal city encoded in UTF-8, not to exceed 64 characters. Authorised characters: numbers, unicode letters, apostrophes, commas, hyphens, full stops and spaces. Characters not allowed: special characters:! @ # $ % & * ( ) _ + = { } [ ] | ; : " < > ? / mathematical symbols: / = < > ^ % | punctuation characters, diacritical characters.
      • postalCode: The signatory's postal code encoded in UTF-8 and containing only numbers.
      • countryCode: The country code of the signatory encoded in UTF-8 and respecting the [ISO3166-1] standard (https://www.iso.org/fr/iso-3166-country-codes.html).
    • phone: the signatory's landline telephone number (may start with +33).
    • externalId: External identifier of the participant
    • birthDate: the date of birth of the signatory in YYYY-MM-DD format (ISO8601).
    • signatures: the list of documents that the participant must sign:
      • documentToSignId: the identifier of the document to be signed (as defined in the course configuration interface)
      • visualIds: the identifiers of the signature visuals to be used in the document. If the table is empty, the contract will not be signed (only viewed by the user). At least one of the defined contracts must have a link to a visual
{
    "type": "sign",
    "civility": "MR",
    "firstName": "John",
    "lastName": "Doe",
    "email": "j.doe@example.com",
    "mobilePhone": "0606060606",
    "birthDate": "1970-02-12",
    "birthPlace": "MACON",
    "externalId": "idExterne",
    "postalAddress": {
        "address1": "123 rue Victor Hugo",
        "postalCode": "75000",
        "city": "Paris"
    },
    "signatures": [
        {
            "documentToSignId": "my-contract",
            "visualIds": [
                "visual-01"
            ]
        }
    ]
}

** Back **

no

Updating business information in a file

Business information can be updated (added and/or modified) during the life cycle of a case. It is no longer modifiable when the case is in a final state (accepted or rejected).

When making an update API call, all business-related information must be included in the request body, including fields that are not being modified. Any field that is omitted will automatically be reset to an empty string.

WARNING: To avoid data loss, always make sure to send a complete payload containing all business values, even those that haven’t changed.

** Request **

Content-Type: multipart/form-data
PUT /v6/integration/client-files/{clientFileUuid}/external-info
  • clientFileUuid (*): the technical identifier of the file

Query content

  • externalInfo: additional data from the file. This value value must be in the form of a JSON encoded in UTF-8. It is a list of keys/values to add or update business information to an existing an existing file. Each value must be a string encoded in in UTF-8
{
    "clientId": "123456789",
    "my_key": "my_value"
}

** Back **

no

Update of documents to be signed

The documents to be signed can only be updated before signing. It is only possible to modify the documents added when the file was created.

** Inquiry**

Content-Type: multipart/form-data
PUT /v6/integration/client-files/{clientFileUuid}/sign-documents
  • clientFileUuid (*): the technical identifier of the file retrieved at creation

Query content

  • documentToSign-{id} (*): binary data of the PDF documents that will be signed. The id value corresponds to the document identifier defined in Workflow. Only documents to be signed, or all documents can be sent (even those which, for reasons of inactivation reasons, will not be signed); in the first case, the modification of the profiles during an update of the file is not of the file is not possible because some documents might be missing. If the signature is deactivated for this pathway, this field should not be set.

  • documentTemplateFields-{id}: a JSON containing information that can be inserted into the PDF templates. This JSON contains key/value pairs with key = name of the field in the PDF form. The values differ depending on the type of field:

    • text: a simple text (can contain variables)
    • checkbox: a boolean (true to check / false to uncheck)
    • choice (drop-down list, group of radio buttons, etc.): the name of the choice

** Back **

no

Updating of supporting documents

The annexed documents can be updated (added and/or modified) during the life cycle of a file. They can no longer be modified when the file is in a final state (accepted or rejected).

** Request **

Content-Type: multipart/form-data
PUT /v6/integration/client-files/{clientFileUuid}/appendices
  • clientFileUuid (*): the technical identifier of the file retrieved during its creation

Query content

  • appendix-{id}: binary data of the appendix files that will be saved with the rest of the documents (archive and proof file). The form-data parameter filename is mandatory

Example:

Content-Disposition: form-data; name="appendix-doc1"; filename="doc1.pdf"
Content-Type: application/pdf

binary data

** Back **

no

Group update

The group can be updated throughout the life cycle of a file.

** Request **

PUT /v6/integration/client-files/{clientFileUuid}/group/{groupLabel}
  • clientFileUuid (*) : the technical identifier of the file retrieved during its creation
  • groupLabel (*) : label of the new group

Query content

vacuum

** Back **

no

Search for files

** Request **

GET /v6/integration/client-files/search

Query parameters

This call can return a large number of files. For this we use a paging system (see parameters "page" and "perPage").

  • page: the index of the page to be retrieved (the first page has index 0). By default the value is 0 ;

  • perPage: number of files on the page. This value must not exceed 1000. The default value is 1000 ;

  • exported: a boolean indicating whether the exported files should be included in the return. If its value is true, then only exported folders are returned in the response. If its value is false, then only non-exported files are returned. are returned. If the parameter is omitted, then all folders are returned;

  • state: search for files by their state. To return several states at once, use this parameter as many times as necessary;

  • externalId: search for files using an external identifier;

  • creationDateFrom and creationDateTo: search for records created in the given time interval. These values must be in ISO8601 format or represent the number of seconds since the time epoch (01/01/1970);

  • participantName: search for files based on the name of one of the participants. This parameter manages surnames, first names and birth names;

  • participantEmail: search for files using the email address of one of the participants;

  • participantMobilePhone: search for files using the mobile phone number of one of the participants;

/v6/integration/client-files/search?exported=false&state=WAITING&state=SUSPENDED&page=0&perPage=500
/v6/integration/client-files/search?state=WAITING&creationDateFrom=2018-01-01T12%3A00%3A00.000Z&creationDateTo=2018-02-01T12%3A00%3A00.000Z
/v6/integration/client-files/search?state=WAITING&creationDateFrom=1526135291&creationDateTo=1528727291

** Back **

The return is in the form of a "paginated" JSON. The records are sorted by date of creation (oldest to newest). The JSON contains the following keys:

  • page: the index of the page (as given as input to the service) ;
  • perPage: the number of values requested in this page;
  • values: the list of uuids identifying the client records. To get more details about the returned records, you will have to use the retrieve-file-information call.

To find out if you are on the last page, check that the number of "values" is lower than "perPage".

{
    "page": 0,
    "perPage": 500,
    "values": [
        "2a35ed70-cc59-11e3-b644-e3907c571fd3",
        "2e45ef64-cc59-11e3-b5a0-672ab5fc322f"
    ]
}

Retrieving information from a file

This call allows the retrieval of essential information on a given file (name of the signatories, creation date...)

** Request **

GET /v6/integration/client-files/{clientFileUuid}?withReport=false
  • clientFileUuid (*) : the technical identifier of the file
  • withReport : includes the report in json format if true. Default value: false.

** Back **

A JSON object containing the following information:

  • creationDate: the date of creation of the file;
  • finishDate: the date of closure of the file (only present if the file is accepted or rejected);
  • externalInfo: JSON containing the external information defined when the file was created
{
    "clientId": "123456789",
    "my_key": "my_value"
}
  • externalId: external identifier given when the file was created
  • rejectionCause: the cause of the rejection of the file (only present if the file has been rejected);
  • validationMessage: the message entered by an operator when the file is accepted or rejected;
  • state: the state of the file ;
  • workflowLabel: the label of the workflow used for the file;
  • archivingState: the archiving state of the file. The following values are possible:
    • NO_ARCHIVING: archiving is not activated for this file
    • ARCHIVED: the file has been archived
    • NOT_YET_ARCHIVED: the file is not yet archived
    • NOT_ARCHIVED: the file has not been archived because it has been rejected or the archiving deadline has passed
  • participants: the information of the participants in the form of a JSON table
    • type: the type of participant as defined in the course configuration interface;
    • state: the state of each participant
    • accessToken: the token used to identify the folder when calling "/api" ; civility : the civil status of the participant
    • civility: the civility (MR, MRS, MISS or UNKNOWN) ;
    • email: email address of the signatory;
    • birthName: the signatory's birth name;
    • postalAddress: the signatory's postal address. This is a JSON containing the fields postalAddress1, postalAddress2, postalAddress3, postalCode, city and countryCode;
    • mobilePhone: mobile phone number;
    • phone: landline telephone number;
    • externalId: external identifier of the participant
    • birthDate: the date of birth of the signatory
    • downloadDocumentsBeforeSignature: All documents before signing have been uploaded (not present if Forced upload of documents before signing = No)
    • downloadSignedDocuments: All signed documents have been uploaded (not present if Forced upload of documents after signing = No)
    • documentToSign: List of documents that will be signed by the participant.
      • id: Id of the document
      • participantVisualIds : Id of the visuals that will be signed by the participant
      • entityStampVisualIds: Id of the visuals organism of the contract
    • documentToVisualize : List of documents that will be viewed by the participant
      • id: Id of the document
  • signDocuments: the list of documents that can be signed
    • id: the unique identifier of the contract (defined in the course configuration interface). The document will be able to be downloaded thanks to this identifier ;
    • label: the name of the document
  • updatable: boolean indicating whether the information in the file can be updated (names of participants, update of a contract ...)
  • group: the group of the file
    • uuid: group identifier
    • label: label of the group
    • defaultGroup: true if it is the default group of the company
  • amount: the amount of the file
  • report: a report in JSON format containing the basic information of the client file and the list of attachments with their possible integrity checks.
{
    "externalInfo": {
        "my_key": "my_value"
    },
    "externalId": "myExternalId00003",
    "workflowLabel": "workflow-simple",
    "state": "PENDING",
    "id": 10002,
    "creationDate": "2016-09-05T09:50:30Z",
    "uuid": "28af2a55-e815-4725-acdf-2ede49cd6933",
    "updatable": true,
    "participants": [
        {
            "type": "signer",
            "state": "PENDING",
            "firstName": "John",
            "lastName": "Doe",
            "civility": "MR",
            "mobilePhone": "0606060606",
            "profiles": [],
            "birthDate": "1987-03-16",
            "email": "john@doe.com",
            "accessToken": "20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
            "externalId": "idExternal",
            "downloadDocumentsBeforeSignature": true,
            "downloadSignedDocuments": false,
            "documentToSign": [
                {
                    "id": "contract",
                    "participantVisualIds": [
                        "visual-1"
                    ],
                    "entityStampVisualIds": [
                        "visual-11"
                    ]
                }
            ],
            "documentToVisualize": [
                {
                    "id": "contract_2"
                }
            ]
        }
    ],
    "signDocuments": [
        {
            "id": "contract",
            "label": "My contract"
        }
    ],
    "group": {
        "uuid": "8cb80ab2-a689-4568-ab85-07c33203842b",
        "label": "DEFAULT",
        "defaultGroup": "true"
    },
    "report": {
        ...
    }
}

Retrieving a document for signature

** Request **

GET /v6/integration/client-files/{clientFileUuid}/sign-documents/{documentId}
  • clientFileUuid (*): the technical identifier of the file
  • documentId (*): the identifier of the document to download. This identifier can be retrieved from the retrieve-file-information call

** Response **

The document bitstream.

Retrieving a submitted files

** Request **

GET /v6/integration/client-files/{clientFileUuid}/files/{fileId}
  • clientFileUuid (*): the technical identifier of the file
  • fileId (*): the identifier of the file to download

** Response **

The document bitstream.

Retrieving a customer file archive

The archive can be retrieved at any time.

The file report.json contained in the archive returned by this service must be kept in the client's IS as it contains essential information such as the reference of the legal archive. because it contains essential information such as the reference of the legal archive.

As a reminder: closed files (accepted or rejected) are kept for 3 months (by default) before being anonymised.

** Request **

GET /v6/integration/client-files/{clientFileUuid}/archive
  • clientFileUuid (*): the technical identifier of the file

** Response **

The direct stream on the archive in ZIP format. This archive contains

  • supporting documents provided by the client
  • any supporting documents
  • Documents that can be signed
  • a report in JSON format containing the basic information of the client file and the list of attached documents with their possible integrity checks.
  • a report in PDF format

Retrieving the evidence file

This file comes from the trusted third party. It contains the signed contract and the documents submitted by the user. Only for accepted clientfiles.

** Request **

GET /v6/integration/client-files/{clientFileUuid}/proof-file
  • clientFileUuid (*) : the technical identifier of the file

** Response **

The flow of the evidence file contains:

  • in the case of Docusign a file in docx format
  • in the case of Namirial a file in 7zip format

Indicate that a customer file has been exported

Once a client file has been processed, so that it is no longer returned to the list of files to be processed, it must be marked as exported.

** Request **

Content-Type: application/x-www-form-urlencoded
PUT /v6/integration/client-files/{clientFileUuid}/export
  • clientFileUuid (*): the technical identifier of the file

** Response **

no

Acceptance of a client file

When a file is recognised as valid, it must be reported to the server. This acceptance will trigger the legal archiving of the file if the signature is activated in the file path. This operation can only be performed on files that are in the WAITING state (awaiting validation). This is a final operation.

Files that are not accepted will not be archived.

** Request **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/accept
  • clientFileUuid (*): the technical identifier of the file

Request headers

  • USER (*): identifier of the operator responsible for the acceptance (for example a physical user or a generic user of type batch).

Query content

  • message (*): comment

** Response **

no

Archiving a file

If "delayed" archiving is activated on a file, it can be triggered by this call.

This only works on accepted files that have the NOT_YET_ARCHIVED (see the retrieve-file-information API).

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/archive
  • clientFileUuid (*): the technical identifier of the file

Request headers

  • USER (*): identifier of the operator responsible for archiving (for example a physical user or a generic batch user).

Query content

no

** Response **

no

Cancelling the archiving of a file

If "delayed" archiving is activated on a file, it can be cancelled by this call.

This only works on accepted files that have the NOT_YET_ARCHIVED (see the retrieve-file-information API).

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/archive/cancel
  • clientFileUuid (*) : the technical identifier of the file

Request headers

  • USER (*): identifier of the operator responsible for the cancellation (for example a physical user or a generic user of type batch).

Query content

no

** Response **

no

Rejection of a client file

If a client file is not valid (see cases below), it may be rejected. This will avoid legal archiving. This is a final action.

** Request **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/reject
  • clientFileUuid (*) : the technical identifier of the file

Request headers

  • USER (*): identifier of the operator responsible for the rejection (for example a physical user or a generic user of type batch).

Query content

** Response **

no

Unlocking a client file

If a file is in the SUSPENDED state, it can be unlocked by this call. For more details on the tasks that caused this caused this blocking, you should read the report.json file.

** Request **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/unblock
  • clientFileUuid (*) : the technical identifier of the file

Request headers

  • USER (*): identifier of the operator responsible for the unblocking (for example a physical user or a generic batch user).

Query parameters

  • message: a comment.

** Response **

no

Reopening a client file

Reopening can be done when the file is either in the WAITING state (after user finalisation) or in the SUSPENDED state.

When reopening, it is possible to accept some bids, reject others, and request additional documents. documents.

It is also possible to reopen a file for signature: in this case all participants will have to sign again; the new documents to be signed must be provided in the multipart request, in the same way as in the folder creation.

Constraint when reopening a document submission task that precedes a facial recognition task: in this case it is not possible to resubmit the document alone, it is necessary to reopen the two linked tasks (document + face match). However, it is possible to re-submit only the facial identification. facial identification only.

Reopening a participant identity task will reopen the signatures of all participants if a participant has already completed his signature.

A folder flagged as "exported" and then re-opened, will appear again in the list of non-exported folders (automatic removal of the "exported" flag).

** Request **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/reopen
  • clientFileUuid (*): the technical identifier of the file

Request headers

  • USER (*): identifier of the operator responsible for the reopening (for example a physical user or a generic user of type batch).

Query content

The lists of task identifiers described in the following must be retrieved from the report.json, field taskId at the level of the list of documents and the face-match list. To request a signature again, specify the identifiers of the signature tasks in the event table (tasks of "type": "SIGNATURE", field taskId).

The value of these identifiers is dynamic and subject to change.

  • reopenedTasks (*): list of document and facial recognition tasks to be reopened (in a JSONArray). See above on how to determine these technical identifiers.
  • acceptedTasks: list of accepted tasks that should not be reopened (in a JSONArray). These identifiers must be retrieved from from the report.json (key taskId)
  • message: a comment
  • extraDocuments: a list of additional documents to be added to the file. This field should only be present for files in the WAITING state. WAITING state. Each entry must contain the fields owner (uuid of the participant), description (a description of the document) and label (document identifier)
[
    {
        "owner": "06ef3650-c999-4c30-a538-b771fbcc807d",
        "description": "Additional document",
        "label": "extra document"
    }
]
  • documentToSign-{id}: new contracts to be signed, if signing tasks have been re-opened.
  • documentTemplateFields-{id}: new information from PDF templates, if signing tasks have been re-opened.

** Response **

no

Accepting a task

If a submitted document is to be validated, it can be accepted.

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/tasks/{taskId}/accept/
  • clientFileUuid (*): the technical identifier of the file.
  • taskId: the technical identifier of the task The lists of task identifiers described in the following must be retrieved from the report.json, field taskId at the level of the list of documents and the list of face-matches.

Request headers

  • USER (*): identifier of the operator responsible for the rejection (for example a physical user or a generic user of type batch).

Query content

no

** Response **

no

Rejecting a task

If a submitted document is to be validated, it can be rejected with a cause.

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/tasks/{taskId}/reject/
  • clientFileUuid (*): the technical identifier of the file.
  • taskId: the technical identifier of the task The lists of task identifiers described in the following must be retrieved from the report.json, field taskId at the level of the list of documents and the list of face-matches.

Request headers

  • USER (*): identifier of the operator responsible for the rejection (for example a physical user or a generic user of type batch).

Query content

** Response **

no

Cancelling the validation of a task

If a submitted document is validated with one of the APIs accept or reject, that validation can be undone to be accepted or rejected again.

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/tasks/{taskId}/cancel/
  • clientFileUuid (*) : the technical identifier of the file.
  • taskId : the technical identifier of the task The lists of task identifiers described in the following must be retrieved from the report.json, field taskId at the level of the list of documents and the list of face-matches.

Request headers

  • USER (*): identifier of the operator responsible for the rejection (for example a physical user or a generic user of type batch).

Query content

no

** Response **

no

Submitting a document

Supporting documents can be sent via this API. The file should be in PENDING status.

** Request **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/documents/{attachmentId}
  • clientFileUuid (*): the technical identifier of the file
  • attachmentId (*): the document identifier as defined in the "Identifier" field of the path (tab "Justificatifs")

Query content

  • participantUuid (*): the identifier of the participant who submits the document
  • documentId (*): the identifier of the document. For documents present in the list of supported document types, its value must be the name of the type. For example, "ID_CARD" for an identity card. For generic documents, it is visible in the path configuration interface (tab "Justificatifs"), for example the value can be "generic_1".
  • documentType (*): the document type submitted in this call. This is useful when a submission task accepts multiple types. This parameter is deprecated; it is preferable to use the "documentId" parameter.
  • file-{x} (*): the binary data of the document to submit. The {x} value must be replaced by an incremental index starting at 1. It is used to submit several files for the same document. For example, for a scan of three For example, for a scan of three pages, each of which is in JPEG format, the parameters file-1, file-2 and file-3 must be sent.

** Response **

If decision support is not enabled, the service returns no data (HTTP/204). In the other case, the extracted data extracted and the checks will be returned:

  • documentType: the detected document type
  • documentDetails: the data extracted from the document
    • holder: the information of the document owner (name, first name, date of birth ...)
    • document: the document information (../date, keywords ...)
  • controlsGroups: the controls performed on the document with their status (OK=no problem, KO=a problem detected, SKIPPED=control not performed). They are grouped in the following categories:
    • document: controls related to document information (may contain the verification of an external control such as DocVerify)
    • documentAspect - controls related to the appearance of the document
    • documentHolder: controls related to the document owner
    • legalEntity: controls related to the legal entity
    • externalData: controls between the document information and an external source (e.g. tax site)
  • pages : List of page information
    • skewAngle: Orientation of the page
  • remainingTries: remaining tries for this document submission
  • errors : list of errors raised while processing the document
  • keysWithError : list of keys in controlsGroups which are in error. This field is of the form "{group}.{control}" (eg: " documentHolder.fullNameFound")

The return differs according to the type of document:

RIB

The key documentDetails/document/iban key contains the IBAN value read from the document. The key documentDetails/document/bicCode contains the value of the BIC code.

The following checks can be made on the document:

Name of the control Description
typeRecognized The system has recognized the type of document
ibanFound An IBAN was found in the document
bicCodeFound BIC code was found in the document
ibanFormatValid The IBAN format is correct
ibanMatch The IBAN value matches the one in the file. If no IBAN was defined when the file was created, this control will always have the value SKIPPED
ibanBankCountryValid the country of the IBAN is allowed. If all countries have been authorised from the Trust and Sign administration interface, this control will always have the value SKIPPED
fullNameFound The participant's name was found in the document. 
{
    "documentType": "RIB",
    "documentDetails": {
        "document": {
            "iban": "FR7000000000000000000000000",
            "bicCode": "CEPAFRPP348"
        },
        "holder": {
            "lastName": "DOE",
            "firstNames": [
                "JOHN"
            ]
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "ibanFound": "OK",
            "bicCodeFound": "OK",
            "ibanChecksumValid": "OK",
            "ibanMatch": "SKIPPED",
            "ibanBankCountryValid": "SKIPPED"
        },
        "documentHolder": {
            "fullNameFound": "OK"
        }
    }
}

Pay slip.

The value nir contains the social security number of the pay slip's owner.

The following checks can be made on the document:

Name of the control Description
typeRecognized the system recognized the type of document
dateFound the date the pay slip was issued was found
maxAgeNotExceeded the date the document was issued does not exceed the maximum date defined in the Trust and Sign administration interface
fullNameFound the participant's name was found in the document
postalAddressMatch the postal address found matches that of the participant. If the address was not defined when the file was created, this control will always have the value SKIPPED
legalEntity the postal address found matches that of the participant.
legalEntityIdExists indicates if the company (whose SIRET is present on the payslip) exists
legalEntityOfficeIdExists indicates if the company establishment (whose SIRET is present on the payslip) exists or existed in the past
legalEntityOfficeAlive indicates if the company's establishment (whose SIRET is present on the payslip) is still open 
{
    "documentType": "PAYSLIP",
    "documentDetails": {
        "document": {
            "nir": "000000000000000",
            "legalEntityOfficeId": "00000000000000",
            "periodDate": "2015-06-01",
            "annualNetTaxableIncome": 25054.29,
            "monthlyNetTaxableIncome": 25054.29,
            "legalEntityAddress": "123 rue Victor Hugo"
        },
        "holder": {
            "lastName": "DOE",
            "firstNames": [
                "JOHN"
            ]
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "dateFound": "OK",
            "maxAgeNotExceeded": "OK"
        },
        "documentHolder": {
            "fullNameFound": "OK",
            "postalAddressFound": "SKIPPED",
            "postalAddressMatch": "SKIPPED"
        },
        "legalEntity": {
            "legalEntityAlive": "OK",
            "legalEntityIdExists": "OK",
            "legalEntityOfficeIdExists": "OK",
            "legalEntityOfficeAlive": "OK"
        }
    }
}

Notice of tax assessment

Warning, following the closure of the tax site, some of these controls have been depreciated. These can be replaced by information extracted from doc2D on the document.

The following checks can be made on the document:

Name of the control Description
typeRecognized the system recognized the type of document
dateFound the date the tax notice was issued was found
maxAgeNotExceeded the date the document was issued does not exceed the maximum date defined in the Trust and Sign administration interface
fullNameFound the participant's name was found in the document
postalAddressFound a postal address has been found in the document and it matches the address on the clientFile. If the address was not defined when the clientFile was created, this control will always have the value SKIPPED
fullNameMatch (new) the participant's name was found in the doc2D and matches with the name in the clientFile
taxNoticeReferenceFound (new) the notice reference was found in the document
fiscalNumberFound (new) at least one fiscal number was found in the document
doc2DFound (new) the doc2D exists and was found on the document, some tax notices do not have a doc2D
doc2DValid (new) the doc2D on the document is valid
doc2DAndDocumentMatch (new) all the controls between the doc2D and the document are OK (result of all the following controls : doc2DAndDocumentTypeMatch, doc2DAndFullName1Match, doc2DAndFullName2Match, doc2DAndReferenceIncomeMatch and doc2DAndIncomeYearMatch. This control will have the value SKIPPED if the doc2DFound control does not have the value OK
doc2DAndDocumentTypeMatch (new) the document's type recognized by the system matches with the document's type extracted from the doc2D. This control will have the value SKIPPED if the doc2DFound control does not have the value OK
doc2DAndFullName1Match (new) the name of the first filer matches between the document and the name extracted from the doc2D. This control will have the value SKIPPED if the doc2DFound control does not have the value OK
doc2DAndFullName2Match (new) the name of the second filer matches between the document and the name extracted from the doc2D. This control will have the value SKIPPED if the doc2DFound control does not have the value OK
doc2DAndReferenceIncomeMatch (new) the reference tax income corresponds between the document and doc2D. This control will have the value SKIPPED if the doc2DFound control does not have the value OK
doc2DAndIncomeYearMatch (new) the year for which income tax is calculated found on the document matches the year detected in doc2D. This control will have the value SKIPPED if the doc2DFound control does not have the value OK
issuanceDateMatch (deprecated) the date of issue of the notice corresponds to the date from the tax site
checkable (deprecated) the document is checkable because it is always present on the tax site (a notice is available for two years)
fullNameMatch (deprecated) participant's name matches between the file and the tax site
identifiersExist (deprecated) identifiers of the tax notice exist on the tax site
refIncomeMatch (deprecated) income amount found in the document matches that returned by the tax site
postalAddressMatch (deprecated) the postal address found matches that of the participant. If the address was not defined when the file was created, this control will always have the value SKIPPED (this control is only available in the "externalData" group)

New return payload based on information extracted from the doc2D present on the document.

{
    "documentType": "TAX_NOTICE",
    "documentDetails": {
        "document": {
            "issuanceDate": "2016-04-24",
            "fiscalNumber1": "0000000000000C",
            "fiscalNumber2": "1000000000000C",
            "reference": "0000000000000",
            "refIncome": "15000",
            "incomeYear": 2021,
            "doc2D": {
                "documentType": "TAX_NOTICE",
                "signedBy": "C=COUNTRYCODE, O=ORGANISM, OU=0000 00000000000000, CN=0000",
                "signatureDate": "2016-04-24",
                "fullName1": "DOE JOHN JAMES",
                "fiscalNumber1": "0000000000000C",
                "fiscalNumber2": "1000000000000C",
                "taxNoticeReference": "0000000000000",
                "referenceIncome": 15000,
                "partsCount": 1,
                "incomeYear": 2021,
                "assessmentDate": "2016-04-24"
            }
        },
        "holder": {
            "firstName": "JOHN",
            "firstNames": [
                "JOHN"
            ],
            "lastName": "DOE",
            "rawAddress": "ADDRESS1 POSTALCODE CITY"
        }
    },
    "controlsGroups": {
        "document": {
            "dateFound": "OK",
            "maxAgeNotExceeded": "OK",
            "typeRecognized": "OK",
            "doc2DFound": "OK",
            "doc2DValid": "OK",
            "doc2DAndDocumentMatch": "OK",
            "taxNoticeReferenceFound": "OK",
            "fiscalNumberFound": "OK",
            "doc2DAndDocumentTypeMatch": "OK",
            "doc2DAndFullName1Match": "OK",
            "doc2DAndFullName2Match": "SKIPPED",
            "doc2DAndReferenceIncomeMatch": "OK",
            "doc2DAndIncomeYearMatch": "OK"
        },
        "documentHolder": {
            "fullNameFound": "OK",
            "postalAddressFound": "KO",
            "fullNameMatch": "OK"
        }
    }
}

Old depreciated return payload based on information returned by the tax site service, which is no longer functional.

{
    "documentType": "TAX_JUSTIFICATION",
    "documentDetails": {
        "document": {
            "reference": "0000000000000",
            "fiscalNumber1": "0000000000000C",
            "refIncome": "15000",
            "fiscalNumber2": "0000000000000C",
            "issueDate": "2016-04-24",
            "incomesDetails": [
                {
                    "name": "DECLARANT_1",
                    "incomes": [
                        {
                            "label": "DEDUCTION 10 OR ACTUAL COSTS",
                            "value": -1000
                        },
                        {
                            "label": "SALARIES",
                            "value": 30000
                        },
                        {
                            "label": "NET WAGES PENSIONS PENSIONS",
                            "value": 32000
                        }
                    ]
                }
            ]
        },
        "holder": {
            "lastName": "DOE",
            "firstNames": [
                "JOHN"
            ]
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "dateFound": "OK",
            "maxAgeNotExceeded": "OK"
        },
        "documentHolder": {
            "fullNameFound": "OK",
            "postalAddressFound": "SKIPPED",
            "postalAddressMatch": "SKIPPED"
        },
        "externalData": {
            "issuanceDateMatch": "OK",
            "checkable": "OK",
            "fullNameMatch": "OK",
            "birthDateMatch": "OK",
            "postalAddressMatch": "OK",
            "identifiersExists": "OK",
            "refIncomeMatch": "OK"
        }
    }
}

Identity documents

Unless otherwise specified, this return is identical for identity cards, passports, residence permits and driving licences.

The following checks can be made on the document:

Name of the control Description
typeRecognized the system has recognized the type of document
mrzValid indicates that the ZLA lines are correct (checksum)
documentCountryValid the country of the document is authorised. If all countries have been authorized in the *Trust and Sign administration interface, this check will always return SKIPPED
documentAppearanceValid the appearance of the document is correct (ZLA line consistent with the appearance of the rest of the document)
birthDateMatch the date of birth extracted from the document matches that of the participant
fullNameMatch the name of the participant matches the name found in the document
civilityMatch the participant's civility matches that found in the document
birthPlaceMatch (French NICs only) the participant's city of birth matches that found in the document.
ocrMrzBirthDateMatch The date of birth is consistent between the MRZ and the rest of the document.
ocrMrzBirthNameMatch The birthname is consistent between the MRZ and the rest of the document.
ocrMrzFirstNamesMatch The firstnames are consistent between the MRZ and the rest of the document.
ocrMrzDocumentNumberMatch The document number is consistent between the MRZ and the rest of the document.
faithfulFont Font looks consistent (only for French ID cards)
ExpirationDateRead Expiration date has been read
DocumentExpirationValid document has not expired
issuanceDateRead Issue date has been read
issuanceAndExpirationDateMatch Issue and expiration dates are consistent
securityElementsValid The following security elements are correct:
  • Initials in the upper right corner of the French passport photo
  • Number of perforations on the French passport
  • Basic consistency between passport number and expiry date
issuerReferentialConnectorSuccess The connection between Trust & Sign and the Issuer Referential service has been established.
issuerReferentialKnownDocument The document sent has been found in the Issuer Referential.
issuerReferentialValid The document has been validated by the Issuer Referential.
issuerReferentialHolderValid The birthName and firstName extracted from the document are consistent with the issuer referential.
notSpecimen The document sent is not a specimen.
backSideFound The backside of the document has not been found
frontSideFound The frontside of the document has not been found

Checks with the repository (issuerReferential*) are used only :

  • for identity documents
  • if the quality of the document is sufficient
  • the document number could be extracted
  • the date of issue of the document could be extracted
  • the date of issue of the MRZ is consistent with the date of issue of the OCR
  • the date of issue is consistent with the expiry date of the document
  • the MRZ is correct
{
    "documentType": "ID_CARD",
    "documentDetails": {
        "document": {
            "issuanceCountry": "FR",
            "issuanceDate": "1988-06-22",
            "expirationDate": "1998-06-21",
            "number": "880692310285"
        },
        "holder": {
            "firstNames": [
                "CORINNE"
            ],
            "firstName": "CORINNE",
            "gender": "F",
            "birthDate": "1965-12-06",
            "birthName": "BERTHIER",
            "birthPlace": "PARIS 1ER (75",
            "rawAddress": "104 RUE DES FLEURS\n 92100 BOULOGNE BILLANCOURT"
        },
        "mrz": {
            "line1": "IDFRABERTHIER<<<<<<<<<<<<<<<<<<<<<<<",
            "line2": "8806923102858CORINNE<<<<<<<6512068F6"
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "ocrMrzDocumentNumberMatch": "OK",
            "issuanceDateRead": "OK",
            "faithfulFont": "OK",
            "ocrMrzBirthNameMatch": "OK",
            "ocrMrzIssuanceDateMatch": "OK",
            "ocrMrzFirstNamesMatch": "OK",
            "documentCountryValid": "SKIPPED",
            "securityElementsValid": "OK",
            "expirationDateRead": "OK",
            "ocrMrzBirthDateMatch": "OK",
            "mrzValid": "OK",
            "backSideFound": "OK",
            "documentExpirationValid": "SKIPPED",
            "issuanceAndExpirationDateMatch": "OK",
            "issuerReferentialConnectorSuccess": "OK",
            "issuerReferentialKnownDocument": "OK",
            "issuerReferentialValid": "OK"
        },
        "documentAspect": {
            "modelValid": "OK",
            "documentAppearanceValid": "OK"
        },
        "documentHolder": {
            "firstLastNamesNotInverted": "OK",
            "birthPlaceMatch": "OK",
            "lastNameMatch": "OK",
            "birthNameMatch": "OK",
            "namesNotInverted": "OK",
            "birthDateMatch": "OK",
            "fullNameMatch": "OK",
            "firstNameMatch": "OK",
            "civilityMatch": "OK"
        }
    },
    "pages": [
        {
            "skewAngle": 6.279538631439209
        },
        {
            "skewAngle": -0.005252533592283726
        }
    ]
}

Italian service card.

The following checks can be made on the document:

Name of the control Description
typeRecognized the system has recognized the type of document
documentExpirationValid document has not expired
documentAppearanceValid The document appearance is correct (ZLA line consistent with the appearance of the rest of the document)
birthDateMatch the date of birth extracted from the document matches that of the participant
fullNameMatch the name of the participant matches the name found in the document
documentNumberValid Card number is valid
personalNumberValid Cardholder number is valid
personalNumberAndHolderMatch Cardholder number and card number are consistent
personalNumberMatch The cardholder number is consistent with the participant's information 
{
    "documentType": "ITA_TS_CNS",
    "documentDetails": {
        "document": {
            "issuanceCountry": "IT",
            "expirationDate": "2026-08-31",
            "number": "110834303223"
        },
        "holder": {
            "firstNames": [
                "JOHN"
            ],
            "birthDate": "1984-08-13",
            "birthName": "DOE",
            "personalNumber": "ABCDE123456789"
        }
    },
    "controlsGroups": {
        "document": {
            "typeRecognized": "OK",
            "mrzValid": "OK",
            "documentExpirationValid": "OK",
            "documentCountryValid": "SKIPPED",
            "documentNumberValid": "OK",
            "personalNumberValid": "OK",
            "personalNumberAndHolderMatch": "OK"
        },
        "documentAspect": {
            "documentAppearanceValid": "OK"
        },
        "documentHolder": {
            "birthDateMatch": "OK",
            "fullNameMatch": "OK",
            "personalNumberMatch": "OK"
        }
    }
}

Resubmission of a document

Supporting documents can be rechecked with this API. Following an update of the file or of a participant, the checks may become obsolete. In this case, this API allows the checks to be re-run with the latest documents submitted.

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/documents/{attachmentId}/reprocess

Query content

  • participantUuid : the identifier of the participant owning the signature task to be rechecked. If this parameter is not present, then the first participant in the file will be used.

** Response **

Same content as the document submission in the Integration API request

Recomparison of a document

After a video identification, the file participant attributes (firstname, lastname, ...) may not be consistant with data read from the video identification. In this case and after the file participant update, this API endpoint allows recomparing file content with video identification extracted data.

Warning: this feature is dedicated to video identification without any other submitted document excepted those provided during the video record.

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/identity-recompare

Query content

  • participantUuid : the identifier of the participant owning the signature task to be rechecked. If this parameter is not present, then the first participant in the file will be used.

** Response **

Same content as the [document submission in the Integration API] request (#submission-dun-document)

Change visibility of documents

Some documents may not be displayed (and therefore submitted) in the Signbook. In this case, they can only be submitted via the [Integration API] (#submission-dun-document).

In case of a problem returned by the document submission API (expired document, wrong name ...) it is advised to make the document the document visible for the participant to submit it.

Hidden documents should be submitted immediately after the dossier has been created so as not to block the end-user's journey. If these documents are submitted only by API, the test counter must be set to 1 to allow the dossier to be finalised.

** Request **

Content-Type: multipart/form-data
POST /v6/integration/client-files/{clientFileUuid}/documents/{attachmentId}/visibility
  • clientFileUuid: the technical identifier of the file
  • attachmentId: the document identifier as defined in the "Identifier" field of the path configuration interface (" Justificatifs" tab) of the path (tab "Justificatifs")

Query content

  • participantUuid: the unique identifier of the participant holding the document to be hidden
  • visiblity: the following values may be used:
    • HIDDEN indicating that the document should not be visible in the Signbook
    • VISIBLE indicating that the document should become visible in the Signbook

** Response **

no

Finalizing a file

This API is only accessible if manual finalisation has been activated in the route configuration interface.

Finalisation is only possible if the file is signed, all documents before signature have been accepted and at least one error-free document submission has been made on each document (from each participant).

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/finalize
  • clientFileUuid: the technical identifier of the file

Request headers

  • USER (*): optional identifier of the operator applying the finalization.

Query content

no

** Response **

no

Submission of a file by a participant

This API is only accessible if manual finalisation has been activated in the route configuration interface.

Submission is only possible if the participant has signed his or her contracts, all documents before signing have been accepted and at least one error-free document submission has been made on each document. Once this submission has been made, this participant will no longer be able to modify his or her documents, but this does not block other participants who have not yet submitted their documents. other participants who have not yet submitted their documents.

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/client-files/{clientFileUuid}/participants/{participantUuid}/complete
  • clientFileUuid: the technical identifier of the file
  • participantUuid: the technical identifier of the participant to be finalised

Query content

  • message: Message from the participant (800 characters at maximum)

** Response **

no

Error handling

If an error occurs during a request, a standard HTTP code is returned with an error JSON containing server-specific code Trust and Sign, an explanatory message and any invalid parameters.

For example:

{
    "error": {
        "message": "Server error",
        "code": 1000
    }
}

Postman collection

A Postman collection (2.1 format) containing the requests documented above.

Once imported, you'll need to modify the variables in the "Variables" tab at the root of the collection.

Service status

A status url is available to allow you to retrieve the operating status of the Trust and Sign platform.

It is advisable to request this service before proceeding with the creation of a file, which will allow, for example, to display an error message to your customers as soon as possible.

** Request **

GET /v6/status

** Response **

HTTP Code 200

It is generally advisable to set a timeout of 90 seconds or more for all your calls.