Developer Pages

# Get process


Contents

This section describes the Get process (opens new window) service. You use this service to retrieve important information about a verification process:

  • The provider used (Onfido, ReadID etc.).
  • The process type (attended, unattended, selfie, video etc).
  • The status of the process (accepted, rejected etc.).
  • When the process started and when it was last updated.
  • Provider-specific information about different verification features used in the verification, e.g. facial similarity, document verification etc.
  • The final result with end-user information like first name, last name and date of birth.

# Response structure

The information in the Get process message response depends on the provider that was used and the current status of the process. For example, you will see different information in a process that is pending than in a process that is finished, e.g. accepted.

The structure of the obtained JSON in the response is divided into three main areas:

Response structure click-to-zoom

Here, Onfido is used as an example. The order of the elements may vary from provider to provider.

# Process information

This message area contains general information about the process, e.g. its internal unique ID, the provider that is used for performing the verification and the dates the process is created and last updated. This information is generated as soon as the process is created.

Here is a response example of Get process as soon as the process was created:

    {
        "provider": "onfido",
        "status": "pending",
        "processId": "4e48363a-37cb-4cff-8f91-afc9e52271fc",
        "createdAt": "2019-09-19T22:10:56Z",
        "updatedAt": "2019-09-19T22:10:56Z"
    }

For more detailed descriptions about status, see:

For all field descriptions, see the OpenAPI documentation (opens new window).

# Status

The status of a process can either be final or not final:

  • pending and processing are not final, meaning the process is not yet finished and the status will still change.
  • accepted, rejected, inconclusive, canceled, failed are all final, meaning the process is now finished and, therefore, its status will not suffer any more changes.

# Not final

Status value Description
pending The process is created but the verification has not yet started.
processing The verification of the data in the process has started but is not yet finished.

# Final

Statuses that are final can be broken into finished with success or finished without success:

  • accepted, rejected, inconclusive mean the process was finished successfully, i.e. it was possible to obtain a result on the identity verification.

  • canceled and failed mean that the process ended without success, i.e., it was not possible to get a result.

Status value Success No success Description
accepted x The verification is finished successfully and it is accepted (i.e, the data is valid).
rejected x The verification is finished successfully and it is rejected (i.e, the data is not valid).
inconclusive x The verification is finished successfully and the result is inconclusive (i.e., the data might not be valid).
canceled x The verification is finished without success because it was cancelled by the end-user.
failed x The verification is finished without success because an error prevented the verification from completing. For example, it could be that the process has timed out due to inactivity on the end-user side or that the end-user has denied access to the camera or microphone.

You can find more information about why it failed in the OpenAPI docs > Get process > failReason (opens new window) description. This fail reason varies from provider to provider. For examples on failed processes, see the provider-specific sections further down on this page.

For details on how the final status is mapped for each provider, see Onfido, Electronic IDentification, ReadID and Signicat Paper.

# Provider-specific information

The Get Process response message contains a providerSpecific area with information about the verification process.

Here is an example from Onfido :


}
    "providerSpecific": {
        "facialSimilarity": {
            "result": "clear",
            "imageIntegrity": "clear",
            "faceComparison": "clear",
            "visualAuthenticity": "clear",
            "similarityScore": "high"
        }
    }
}

The contents depend on the information each provider shares and it is filled in gradually as the provider shares this information. For example, some providers start sharing information as soon as the identity document is uploaded, others share information when the verification is complete.

The information in this area is composed of one or more JSON elements containing information about the results of the identity document verification. The number and name of these elements are specific for each provider:

Provider JSON elements in the Get process response
Onfido facialSimilarity, documentVerification
Electronic IDentification ocr, manualApproval
ReadID session
Signicat Paper verification, features, mrz, mrzChecksum, mrzVerification, mrzFeatureMatching
Connect idtoken, userInfo, error
WebID identResponse, payMoneyTransferResponse

For more details about each of these fields, see the providerSpecific element in the OpenAPI docs for Get process (opens new window).

# Normalised final result

After a verification is finished and if the result is accepted, the Assure API generates a finalResult element and adds it to the Get process response. This element contains a fixed summary of provider collated information. The available fields depend on the information obtained from the provider.

Here is an example of a finalResult response:

"finalResult": {
    "firstName": "MARIA PAULA",
    "lastName": "SANTOS MENDES",
    "dateOfExpiry": "2024-03-02",
    "gender": "F",
    "nationality": "PRT",
    "documentType": "passport",
    "documentNumber": "1234567890",
    "issuingCountry": "PRT",
    "dateOfBirth": "2002-04-29",
    "similarityScore": "high",
    "livenessDetected": "true",
    "personalIdentificationNumber": "FANTASYBANK1234567890"
}

For detailed descriptions of these parameters and values, see the OpenAPI documentation > Get process > finalResult (opens new window).

The elements in the responses you get from the Assure API are normalised to follow the same format, e.g. for how the date format (birthdate, date of expiry etc.) should be written (for more details, see Key concepts > Normalisation).

# Results per provider

The provider-specific results are described here:

Last updated: 11/04/2024 07:47 UTC

← Files in dossier →