Verification results webhook

When a client completes the verification - your registered webhook endpoint will receive a HTTP POST request containing data and status of the verification.

Your API must return HTTP response with status code 200. Otherwise, a client will see a failed verification message and will be redirected to a URL of a failed verification.

If you are experiencing any issues receiving a webhook - webhook troubleshooting section.

All of our webhooks are TLS encrypted and require a valid SSL certificate of your webhook endpoint, otherwise, the webhook sending will fail.

Verification and webhook flow

When to expect a webhook

There are certain points of time in identity verification process when your API should expect to receive a webhook.

Your API should expect to receive a webhook up to 20 minutes when:

• A client has successfully completed a verification
• A client has consecutively failed to identify himself and has reached maximum reattempts allowed in the verification platform.
• A client was suspected for a fraudulent activity and his session was terminated.

Your API should not expect to receive up to 20 minutes callback when (In case of these events your API will receive a callback only when a token (token property tokenExpiry) or a token session (token property sessionLength) has expired. For more on these variables refer to generating verification token):

• A client has consecutively failed to identify himself and has not reached maximum reattempts allowed in the verification platform.
• A client did not start a verification session.

Default callback

Default callback is represented in a UML activity graph below:

1. Generate a token by sending an HTTP POST request to https://ivs.Mark ID.com/api/v2/token endpoint. The request must contain basic auth headers, where the username is the API key and the password is API secret.

More information can be found here.

1. Redirect client to Mark ID platform. It can be done in several ways:
   • Client redirect to verification WEB platform
   • Client redirect to verification WEB platform (iFrame)
   • iOS SDK
   • Android SDK
2. Client submits all documents (tries to verify at least one time).

3.1. If a client doesn’t upload all photos at least one time, for example, face photos are missing and only the document’s photo are captured after session time expires Mark ID system will send a callback about expired notification to the provided URL with overall status: ”EXPIRED”.

1. The client completes the verification process. When the verification process is complete, please check here.

4.1. If a client captures all photos at least one time, but verification was unsuccessful while more attempts are available after session time expires Mark ID system will send a callback about expired notification to the provided URL with overall status: ”DENIED”.

1. After the verification process is completed or 4.1 callback sent we will perform full document analysis by automated system and human supervision. The Analysis process can take up to 20 minutes (on average about 10 minutes).
2. After the analysis process is done, we are sending all data to the registered callback URL.
3. Receiving all data sent by Mark ID to your provided endpoint.
4. Returning HTTP status code 200.

8.1. HTTP status code is not 200. Trying to resend callback (max 3 times) every 0,5 seconds.

How many webhooks to expect: If You get a 3.1 callback with overall status EXPIRED it would be just one callback.

If a client does not complete verification and 4.1 step occurs, the system will send a DENIED callback and after automated system and human supervision analysis, we will send the final callback.

In default flow (steps 1, 2, 3, 4, 5, 6, 7) You would get only one callback with final results after human supervision analysis.

Webhooks with auto callback

Callback with automatic callback are represented in a UML activity graph below:

1. Generate a token by sending an HTTP POST request to https://ivs.Mark ID.com/api/v2/token endpoint. The request must contain basic auth headers, where the username is the API key and the password is API secret.

More information can be found here.

1. Redirect the client to the Mark ID platform. It can be done in several ways:
   • Client redirect to verification WEB platform
   • Client redirect to verification WEB platform (iFrame)
   • iOS SDK
   • Android SDK
2. Client submits all documents (tries to verify at least one time).

3.1. If a client doesn’t upload all photos at least one time, for example, face photos are missing and only the document’s photo are captured after session time expires Mark ID system will send a callback about expired notification to the provided URL with overall status: ”EXPIRED”.

1. The client completes the verification process. When the verification process is complete, please check here.

4.1. If a client captures all photos at least one time, but verification was unsuccessful while more attempts are available after session time expires Mark ID system will send a callback about expired notification to the provided URL with overall status: ”DENIED”.

1. After the verification process is completed we will perform full document analysis by the automated system.
2. After the automatic analysis process is done, we are sending all data with auto results to the registered callback URL.
3. Receiving all data with auto results sent by Mark ID to your provided endpoint.
4. Returning HTTP status code 200.

8.1. HTTP status code is not 200. Trying to resend callback (max 3 times) every 0,5 seconds.

1. After the automatic verification process is completed and 200 status received we will perform full document analysis by human supervision. The Analysis process can take up to 20 minutes (on average about 10 minutes).
2. After the manual analysis process is done, we are sending all data with manual results to the registered callback URL.
3. Receiving all data with manual results sent by Mark ID to your provided endpoint.
4. Returning HTTP status code 200.

12.1. HTTP status code is not 200. Trying to resend callback (max 3 times) every 0,5 seconds.

You should expect two webhooks:

• Callback after automatic analysis
• Callback after manual review

If case 3.1 occurs You should expect to get only one callback: Callback about an expired session

Callback structure

Request HTTP body is in JSON format which is described in tables below:

Verification status table

Face and document statuses after manual review table

Data table

Note, that any of the specified fields below can be null. Also, some fields in original language could have symbols encoded in UTF-16.

File URLs table

Examples

This is an example JSON body in the callback HTTP request.

{
  "clientId": "123",
  "scanRef": "scan-ref",
  "externalRef": "external-ref",
  "platform": "MOBILE_APP",
  "startTime": 1554726960, 
  "finishTime": 1554727002,
  "clientIp": 192.0.2.0,
  "clientIpCountry": "LT",
  "clientLocation": "Kaunas, Lithuania",
  "final": false,
  "status": {
    "overall": "APPROVED",
    "suspicionReasons": [],
    "mismatchTags": [],
    "fraudTags": [],
    "autoDocument": "DOC_VALIDATED",
    "autoFace": "FACE_MATCH",
    "manualDocument": "DOC_VALIDATED",
    "manualFace": "FACE_MATCH",
    "additionalSteps": null
  },
  "data": {
    "docFirstName": "FIRST-NAME-EXAMPLE",
    "docLastName": "LAST-NAME-EXAMPLE",
    "docNumber": "XXXXXXXXX",
    "docPersonalCode": "XXXXXXXXX",
    "docExpiry": "YYYY-MM-DD",
    "docDob": "YYYY-MM-DD",
    "docType": "ID_CARD",
    "docSex": "UNDEFINED",
    "docNationality": "LT",
    "docIssuingCountry": "LT",
    "manuallyDataChanged": false,
    "fullName": "FULL-NAME-EXAMPLE",
    "selectedCountry": "LT",
    "orgFirstName": "FIRST-NAME-EXAMPLE",
    "orgLastName":  "LAST-NAME-EXAMPLE",
    "orgNationality": "LIETUVOS",
    "orgBirthPlace": "ŠILUVA",
    "orgAuthority": null,
    "orgAddress": null,
    "selectedCountry": "LT",
    "ageEstimate": "UNDER_13",
    "clientIpProxyRiskLevel": "LOW",
    "duplicateDocFaces": null,
    "duplicateFaces": null,
    "additionalData": {
    "UTILITY_BILL": {
      "ssn": {
        "value": "ssn number",
        "status": "MATCH"
      }
    }
  },
  "manualAddress": null,
  "manualAddressMatch": false,
  },
  "fileUrls": {
    "FRONT": "https://s3.eu-west-1.amazonaws.com/production.users.storage/users_storage/users/<HASH>/FRONT.png?AWSAccessKeyId=<KEY>&Signature=<SIG>&Expires=<STAMP>",
    "BACK": "https://s3.eu-west-1.amazonaws.com/production.users.storage/users_storage/users/<HASH>/BACK.png?AWSAccessKeyId=<KEY>&Signature=<SIG>&Expires=<STAMP>",
    "FACE": "https://s3.eu-west-1.amazonaws.com/production.users.storage/users_storage/users/<HASH>/FACE.png?AWSAccessKeyId=<KEY>&Signature=<SIG>&Expires=<STAMP>"
  },
  "AML": [
  {
      "status": {
        "serviceSuspected": false,
        "checkSuccessful": true,
        "serviceFound": true,
        "serviceUsed": true,
        "overallStatus": "NOT_SUSPECTED"
      },
      "data": [],
      "serviceName": "PilotApiAmlV2",
      "serviceGroupType": "AML",
      "uid": "OHT8GR5ESRF5XROWE5ZGCC123",
      "errorMessage": null
    }
  ],
  "LID": [
  {
      "status": {
        "serviceSuspected": false,
        "checkSuccessful": true,
        "serviceFound": true,
        "serviceUsed": true,
        "overallStatus": "NOT_SUSPECTED"
      },
      "data": [],
      "serviceName": "IrdInvalidPapers",
      "serviceGroupType": "LID",
      "uid": "OHT8GR5ESRF5XROWE5ZGCC123",
      "errorMessage": null
    }
  ]
}

Webhook troubleshooting

Not receiving a callback? These are the first steps you should take in order to resolve an issue:

• Ensure that you have provided a valid callback endpoint (it does not contain typos and is a fully specified URL with HTTP schema, port and domain name).
• Ensure that the provided endpoint can be reached from internet.
• Ensure that your SSL is set up correctly. Our system can only send webhooks to URLs with valid SSL certificates.
• Ensure that you are actually not getting a callback and your framework is not accidentally returning some other HTTP response e.g. 422 or 500.