Get info on an identification for a request

This API call allows you to retrieve the details of a specific identification by its unique identifier.

This API supports common integrations scenarios:

1. Simplest scenario

   1. In case the request type has just one actor and the integrator is interested in retrieving only the latest identification outcome (or the request type supports just one identification process)

2. Simple scenario with multiple actors

   1. Similarly to previous case, the integrator is interested in retrieving only the latest identification outcome (or the request type supports just one identification process)

3. Advanced scenario

   1. The integrator is interested in retrieving the outcome of all idetifications attempts and thie is supported by the request type. This applies both for types with one actor or multiple actors.

1. Simplest scenario

Endpoint

• URL: /request/{id}/identification

• Method: GET

Headers

Ensure you include the following headers in your request:

• Accept: application/json

• X-Api-Key: YOUR_API_KEY (replace YOUR_API_KEY with your actual API key)

Path parameters

• id (required): The unique identifier of the request you want to retrieve the identification for. This should be included in the URL path. Example: 123e4567-e89b-12d3-a456-426614174000

Example cURL API call

Replace YOUR_API_KEY with your actual API key, YOUR_REQUEST_ID with the ID of the request.

Responses

• 404 Not Found

  • Description: The requested resource was not found.

  • Example Response:

    { "type": "about:blank", "status": 404, "title": "Not Found", "detail": "The requested resource was not found.", "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000?ts=1729667463", "retryable": false }

2. Simple scenario with multiple actors

Endpoint

• URL: /request/{id}/identification

• Method: GET

Headers

Ensure you include the following headers in your request:

• Accept: application/json

• X-Api-Key: YOUR_API_KEY (replace YOUR_API_KEY with your actual API key)

Path parameters

• id (required): The unique identifier of the request you want to retrieve the identification for. This should be included in the URL path. Example: 123e4567-e89b-12d3-a456-426614174000

Query parameters

• actor (optional): The name of the actor. According to the endpoint, it may be required if multiple actors are defined for the request type. Example: customer

Example cURL API call

Replace YOUR_API_KEY with your actual API key, YOUR_REQUEST_ID with the ID of the request.

Responses

• 200 OK

  • Description: The details of the requested identification.

  • Example Response:

    { "id": "123e4567-e89b-12d3-a456-426614174001", "actor": "customer", "status": "COMPLETED", "source": "FACEMATCH", "personData": { "firstName": "John", "lastName": "Doe", "birthDate": "1980-01-01", "gender": "M", "nationality": "IT", "phoneNumber": "+393331112233", "email": "john.doe@example.com", "address": "Via del Mondo 9, Firenze, IT" }, "validationDetail": { "personalNumber": "OK", "lastName": "OK", "firstName": "OK", "birthDate": "OK", "gender": "OK", "phoneNumber": "OK", "email": "OK", "documentNumber": "OK" }, "finalizedAt": "2024-10-29T17:42:16Z", "biometryCheck": { "controlsSummary": -3, "keysWithError": [ "faceMatch.idHolderAgeMatch", "faceMatch.passiveLiveness" ] }, "documentCheck": { "documentType": "PASSPORT", "documentTypeFamily": "IDENTITY_DOCUMENT", "controlsSummary": 0, "keysWithError": [] } }

• 404 Not Found

  • Description: The requested resource was not found.

  • Example Response:

    { "type": "about:blank", "status": 404, "title": "Not Found", "detail": "The requested resource was not found.", "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000?ts=1729667463", "retryable": false }

3. Advanced scenario

This scenario requires retrieving information from the Get list of identifications for a request endpoint.

Endpoint

• URL: /request/{id}/identification

• Method: GET

Headers

Ensure you include the following headers in your request:

• Accept: application/json

• X-Api-Key: YOUR_API_KEY (replace YOUR_API_KEY with your actual API key)

Path parameters

• id (required): The unique identifier of the request you want to retrieve the identification for. This should be included in the URL path. Example: 123e4567-e89b-12d3-a456-426614174000

Query parameters

• identificationId (optional): The unique identifier of the identification. If not set, the endpoint returns the last identification. Example: 123e4567-e89b-12d3-a456-426614174001

• actor (optional): The name of the actor. According to the endpoint, it may be required if multiple actors are defined for the request type. Example: customer

Example cURL API call

Replace YOUR_API_KEY with your actual API key, YOUR_REQUEST_ID with the ID of the request, and YOUR_IDENTIFICATION_ID with the ID of the identification.

Responses

• 200 OK

  • Description: The details of the requested identification.

  • Example Response:

    { "id": "123e4567-e89b-12d3-a456-426614174001", "actor": "customer", "status": "COMPLETED", "source": "FACEMATCH", "personData": { "firstName": "John", "lastName": "Doe", "birthDate": "1980-01-01", "gender": "M", "nationality": "IT", "phoneNumber": "+393331112233", "email": "john.doe@example.com", "address": "Via del Mondo 9, Firenze, IT" }, "validationDetail": { "personalNumber": "OK", "lastName": "OK", "firstName": "OK", "birthDate": "OK", "gender": "OK", "phoneNumber": "OK", "email": "OK", "documentNumber": "OK" }, "finalizedAt": "2024-10-29T17:42:16Z", "biometryCheck": { "controlsSummary": -3, "keysWithError": [ "faceMatch.idHolderAgeMatch", "faceMatch.passiveLiveness" ] }, "documentCheck": { "documentType": "PASSPORT", "documentTypeFamily": "IDENTITY_DOCUMENT", "controlsSummary": 0, "keysWithError": [] } }

• 404 Not Found

  • Description: The requested resource was not found.

  • Example Response:

    { "type": "about:blank", "status": 404, "title": "Not Found", "detail": "The requested resource was not found.", "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000?ts=1729667463", "retryable": false }

Biometric and document checks

About ID SELF workflows, there are two special parameters: biometryCheck and documentCheck.

For both the above-mentioned params, there are the following sub-parameters:

• controlsSummary: a number indicating the controls highest failure code. Controls summary can be used for a quick decision, instead of checking each individual control:

  • 0: all controls are OK.

  • -1: at least one quality error

  • -2: at least one document conformity error

  • -3: at least one document consistency or authenticity error

• keysWithErrors: list of controls keys paths with an errors (IDSelf controls reports the list of the controls).

Only documentCheck has the following parameters:

• documentType: ID_CARD, PASSPORT, RESIDENCE_PERMIT, TAX_NOTICE, TAX_JUSTIFICATION, PROPERTY_TAX_NOTICE, LOCAL_RESIDENCE_TAX_NOTICE, RIB, ENERGY_INVOICE, ENERGY_SCHEDULE, PHONE_INVOICE, PAYSLIP, DRIVER_LICENSE, VEHICLE_REGISTRATION_CERTIFICATE, FAMILY_ALLOWANCE, RETIREMENT_PENSION, INSURANCE_ATTESTATION, ITA_TS_CNS, PHOTOGRAPH, UNDEFINED

• documentTypeFamily: BANK_ACCOUNT, TAX_DOCUMENT, ADDRESS_DOCUMENT, PAYSLIP_DOCUMENT, IDENTITY_DOCUMENT, VRC_DOCUMENT, FAMILY_ALLOWANCE_DOCUMENT, INSURANCE_ATTESTATION_DOCUMENT, UNDEFINED