Skip to content

Web Services / Facematch 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. See the example on the Integration API.

Creating a customer file

** Request **

Content-Type: multipart/form-data
POST /v6/integration/facematch

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;

  • 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;

  • 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 folder identifier in the 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 Vistor Hugo",
    "postalCode":"75000",
    "city": "Paris"
  }
}
  • participant*: the participant's information in the form of a JSON encoded in UTF-8. The following keys must be used:
    • civility (*) : the participant's civility (MR, MRS, MISS or UNKNOWN) ;
    • firstName (*) : the participant's first name encoded in UTF-8, containing a maximum of 64 characters (the characters |, /, @, ,, $ and + are not allowed);
    • lastName (*) : the participant's last name encoded in UTF-8, containing a maximum of 64 characters (the characters |, /, @, ,, $ and + 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);
    • birthName: the participant's birth name if it is different from their family name (due to a marriage for example). This string must be encoded in UTF-8, containing a maximum of 64 characters (the characters |, /, @, ,, $ and + are not allowed) ;
    • birthPlace: the participant's place of birth, as it appears on their 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```.
    • iban: the iban to be compared with the document that the participant will provide
    • postalAddress: the postal address of the participant
      • address1 (*) : the first line of the participant'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 participant's postal address encoded in UTF-8 and not exceeding 128 characters.
      • address3: the third line of the participant's postal address encoded in UTF-8 and not exceeding 128 characters.
      • city (*): The postal city of the participant 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 participant's postal code encoded in UTF-8 and containing only numbers.
      • countryCode* : country code where the participant resides encoded in UTF-8 and respecting the [ISO3166-1] standard (https://www.iso.org/fr/iso-3166-country-codes.html).
    • phone*: the participant's fixed telephone number in the format +33666666666 or 0666666666.
    • birthDate: the participant's date of birth in YYYY-MM-DD (ISO8601) format.
    • legalAgent: Boolean indicating that the participant is an agent of the legal entity. This field is only useful if the legal entity is activated in the path
    • externalId: External identifier of the participant
{
  "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"
  }
}

** 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 folder was created
{
  "clientId":"123456789",
  "my_key": "my_value"
}
  • externalId: external identifier given when the file is created
  • uuid : unique identifier of the file
  • id: folder identifier
  • state : the state of the file (PENDING);
  • workflowLabel : the workflow label used for the file;
  • participant: the participant's information
    • uuid: the participant's identifier
    • accessToken: the token used to identify the file when calling `/api
    • civility: the civility (MR, MRS, MISS or UNKNOWN);
    • email: the email address of the participant;
    • birthName: the participant's birth name;
    • postalAddress: postal address of the participant. This is a JSON containing the fields postalAddress1, postalAddress2, postalAddress3, postalCode, city and countryCode;
    • mobilePhone: mobile phone number;
    • phone: landline telephone number;
    • birthDate*: the participant's date of birth
{
  "externalInfo": {
    "my_key": "my_value"
  },
  "externalId": "myExternalId00003",
  "workflowLabel": "workflow-simple",
  "state": "PENDING",
  "id":10002,
  "creationDate":"2020-12-05T09:50:30Z",
  "uuid":"28af2a55-e815-4725-acdf-2ede49cd6933",
  "participant":{
    "uuid":"546875455-e815-4725-acd",
    "firstName": "John",
    "lastName": "Doe",
    "civility": "MR",
    "mobilePhone":"0606060606",
    "profiles":[],
    "birthDate":"1987-03-16",
    "email": "john@doe.com",
    "accessToken": "20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
    "externalId": "idExternal"
  }
}

Update of participant information

The participant's information can be updated. The request must contain all the participant's information, not just the information to be updated.

** Request **

Content-Type: multipart/form-data
PUT /v6/integration/facematch/{clientFileUuid}/participant
  • clientFileUuid ()* : the technical identifier of the file

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:
    • civility (*): the participant's civility (MR, MRS, MISS or UNKNOWN);
    • firstName (*) : the participant's first name 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 standard rfc2822;
    • mobilePhone: the participant's mobile phone number (may start with +33);
    • birthName: the participant's birth name if it is different from his or her family name (due to 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. Note that it is not possible to delete a profile. It is only possible to add one or more profiles. The size must not exceed 256 characters.
    • 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 participant's postal address encoded in UTF-8 and not exceeding 128 characters. If this field is provided, the city and postalCode fields must also be provided;
      • address2: second line of the participant's postal address encoded in UTF-8 and not exceeding 128 characters.
      • address3: the third line of the participant's postal address encoded in UTF-8 and not exceeding 128 characters.
      • city*: The postal city of the participant 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 participant's postal code encoded in UTF-8 and containing only numbers.
      • countryCode*: Country code where the participant resides encoded in UTF-8 and respecting the [ISO3166-1] standard (https://www.iso.org/fr/iso-3166-country-codes.html).
    • phone*: participant's fixed telephone number (may start with +33).
    • externalId: external identifier of the participant
    • birthDate: the participant's date of birth in YYYY-MM-DD format (ISO8601).
{
  "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"
  }
}

** 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 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/facematch/{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

Search for files

** Request **

GET /v6/integration/facematch/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/facematch/search?exported=false&state=WAITING&state=SUSPENDED&page=0&perPage=500
/v6/integration/facematch/search?state=WAITING&creationDateFrom=2018-01-01T12%3A00%3A00.000Z&creationDateTo=2018-02-01T12%3A00%3A00.000Z
/v6/integration/facematch/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 (#recovery-file-information).

To find out if you are on the last page, check that the number of "values" is less 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 participant, creation date, etc.)

** Request **

GET /v6/integration/facematch/{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 workflow label used for the file;
  • participant: the participant's information
    • state : the state of each participant
    • accessToken: the token used to identify the file when calling /api;
    • civility: the civility (MR, MRS, MISS or UNKNOWN);
    • email: the email address of the participant;
    • birthName: the participant's birth name;
    • postalAddress: the participant's postal address. This is a JSON containing the fields postalAddress1, postalAddress2, postalAddress3, postalCode, city and countryCode;
    • mobilePhone: mobile phone number;
    • phone : fixed phone number;
    • externalId: external identifier of the participant
    • birthDate: the date of birth of the participant
  • 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",
  "participants":[{
    "state": "PENDING",
    "firstName": "John",
    "lastName": "Doe",
    "civility": "MR",
    "mobilePhone":"0606060606",
    "profiles":[],
    "birthDate":"1987-03-16",
    "email": "john@doe.com",
    "accessToken":"20161005_eWticz85PZRHhB8gexjWYkK77bXs0f",
    "externalId": "idExternal"
  }],
  "report": {
    ...
  }
}

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/facematch/{clientFileUuid}/archive
  • clientFileUuid (*)* : the technical identifier of the file

** Back **

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

  • supporting documents provided by the client
  • a report in JSON format](../report_json_v6) containing the basic information of the client file and the list of attachments with their possible integrity checks.
  • a report in PDF 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/facematch/{clientFileUuid}/export
  • clientFileUuid (*)* : the technical identifier of the file

** Back **

no

Acceptance of a client file

When a file is recognised as valid, it must be reported to the server. This can only be done on files that are in the that are in the WAITING state. This is a final operation.

**Files that are not accepted will not be archived.

** Request **

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

Request headers.

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

Query content

  • message (*): comment

** Back **

no

Rejection of a client file

If a client file is not valid, it may be rejected. This is a final action.

** Request **

Content-Type: application/x-www-form-urlencoded
POST /v6/integration/facematch/{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

** Back **

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

** Back **

no

Rejecting a task

If a submitted document is to be validated, it may 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

** Back **

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

** Back **

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
  }
}