API Reference

Verify that a selfie shows a real, live person and that it matches a reference photo, using the VIDA Verify API V2. The same endpoint can also check the face against a blacklist.

Choose an operation

What you need	Operations to send	Result
Liveness check	imageLivenessVerification	Is the selfie a live person?
Biometric verification	imageFaceMatchVerification + imageLivenessVerification	Is it a live person, and does the face match the reference photo?
Blacklist check	Enabled on request	Is the face in the blacklist database?

How the checks depend on each other

Both operations in Biometric Verification run concurrently, but face match depends on liveness. Face matching only happens once a live person is confirmed. This prevents spoofed or unauthorized attempts.

imageLivenessVerification
 ├─ Fails → no imageFaceMatchVerification result is returned
 └─ Passes → Blacklist check (only if enabled)
              ├─ Face found → face match is skipped, blacklist response returned
              └─ No match   → imageFaceMatchVerification runs → success response

The overall result of Biometric Verification depends on passing liveness. For liveness details, see Liveness.

Request format

These fields are shared by every operation.

Endpoint

POST https://{vida-host}/api/v2/verify

Headers

Name	Type	Description
Authentication *	String	Bearer <Token>
Content-Type	String	Format type of the request body (application/json)

Body

Name	Type	Description
operations *	Array	Operations to run, for example ["imageLivenessVerification"]
payload *	Object	Data for each operation (see below)
userConsent *	Object	Proof of the user's consent (see below)

payload fields

Field	Type	Rule	Description
partnerTrxId	String	Required	A unique ID you generate for this transaction
groupId	String	Required	An ID that links this request to the rest of the KYC flow
faceImage	String (Base64)	Send this or livenessTransactionIds	The selfie image
livenessTransactionIds	Array	Send this or faceImage	Transaction ID from an earlier Liveness Verification call. Use it instead of sending a new selfie
idFrontSideImage	String (Base64)	Send this or croppedFaceImage (face match)	The front of the ID card
croppedFaceImage	String (Base64)	Send this or idFrontSideImage (face match)	A cropped face image from the reference photo

Send one of faceImage or livenessTransactionIds, not both.

userConsent fields

Field	Type	Description
userIp	String	IP address of the user
country	String	Country code, for example MYS
obtained	Boolean	Whether consent was obtained
obtainedAt	String	Unix timestamp of when consent was obtained

Liveness check

Checks whether the selfie is a live photo. Send only imageLivenessVerification in operations.

JSON - Sample Request

{
  "operations": ["imageLivenessVerification"],
  "payload": {
    "partnerTrxId": "{{$guid}}",
    "groupId": "{{$guid}}",
    "faceImage": "Base64 encoded image"
  },
  "userConsent": {
    "userIp": "226.80.211.232",
    "country": "MYS",
    "obtained": true,
    "obtainedAt": "1680700959"
  }
}

JSON - Sample Response

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
  "imageLivenessVerificationResult": {
    "data": {
      "code": 1043,
      "message": "Selfie photo is a live photo",
      "score": 0.066661
    }
  }
}

Biometric verification

Checks liveness and matches the selfie to a reference photo. Include both imageFaceMatchVerification and imageLivenessVerification in operations, plus the reference photo in payload.

Choose how to send the selfie

	Using faceImage	Using livenessTransactionIds
What you send	A new selfie image	Transaction ID(s) from an earlier Liveness Verification call
Use it when	Liveness and face match happen in one step	You already ran liveness and don't want to capture a new selfie

JSON - Sample Request Using faceImage

{
  "requestOrigin": "SDK",
  "kycFlowType": "KYC",
  "operations": [
    "imageFaceMatchVerification",
    "imageLivenessVerification"
  ],
  "payload": {
    "partnerTrxId": "{{$guid}}",
    "groupId": "{{$guid}}",
    "faceImage": "Base64 encoded image",
    "croppedFaceImage": "Base64 encoded cropped face image"
  },
  "userConsent": {
    "userIp": "226.80.211.232",
    "country": "MYS",
    "obtained": true,
    "obtainedAt": "1680700959"
  }
}

JSON - Sample Request Using livenessTransactionIds

{
  "operations": [
    "imageFaceMatchVerification",
    "imageLivenessVerification"
  ],
  "payload": {
    "partnerTrxId": "internal-test-005",
    "groupId": "030920261235",
    "livenessTransactionIds": ["{{liveness_transactionId}}"],
    "idFrontSideImage": "{{id_front_image}}"
  },
  "userConsent": {
    "userIp": "226.80.211.232",
    "country": "MYS",
    "obtained": true,
    "obtainedAt": "1680700959"
  }
}

JSON - Success Response

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
  "imageFaceMatchVerificationResult": {
    "data": {
      "code": 1042,
      "message": "Selfie photo matches with reference photo",
      "score": 0.941826
    }
  },
  "imageLivenessVerificationResult": {
    "data": {
      "code": 1043,
      "message": "Selfie photo is a live photo",
      "score": 0.198378,
      "imgManipulationScore": 0.091674
    }
  }
}

Blacklist check

Prevents onboarding or verification of users whose facial images appear in a blacklist database. The check runs before face match. If a match is found, the face match step is skipped.

Blacklist Check is enabled on request. Contact VIDA to turn it on for your account.

How it works

1

Check if it is enabled

The system checks whether Blacklist Check is enabled for your product. If yes, the check runs.

2

Blacklist hit

If the face is found in the blacklist, the system returns a response with the matching code and message, and the face match step is skipped.

3

No blacklist match

If no blacklist image is found, the system returns the normal success response, with an empty faceReferences list.

Blacklist Check can run as part of a Liveness Check or as a standalone check, using the same endpoint: POST https://{vida-host}/api/v2/verify.

JSON - Success Response No Match

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
  "imageFaceMatchVerificationResult": {
    "data": {
      "code": 1042,
      "message": "Selfie photo matches with reference photo",
      "score": 0.992796
    }
  },
  "imageLivenessVerificationResult": {
    "data": {
      "code": 1043,
      "message": "Selfie photo is a live photo",
      "score": 0.066661
    }
  },
  "blacklistCheckResult": {
    "faceReferences": []
  }
}

JSON - Success Response Match (Warning)

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
  "warnings": [
    {
      "message": "Image is blacklisted.",
      "code": 10501,
      "operations": ["imageFaceMatchVerification"]
    }
  ],
  "imageFaceMatchVerificationResult": {
    "data": {
      "code": 1042,
      "message": "Selfie photo matches with reference photo",
      "score": 0.992796
    }
  },
  "imageLivenessVerificationResult": {
    "data": {
      "code": 1043,
      "message": "Selfie photo is a live photo",
      "score": 0.066661
    }
  },
  "blacklistCheckResult": {
    "faceReferences": [
      {
        "faceId": "f4640eae-5e10-4405-99ea-051826756fb2",
        "matchScore": 1.0
      }
    ]
  }
}

JSON - Error Response Match

{
  "transactionId": "unique transaction id generated to identify this transaction",
  "partnerTrxId": "partner transaction id submitted by customer in request",
  "groupId": "reference id to track complete KYC flow",
  "errors": [
    {
      "message": "Verification failed: Image is blacklisted.",
      "code": 5801,
      "operations": ["imageFaceMatchVerification"]
    }
  ],
  "imageLivenessVerificationResult": {
    "data": {
      "code": 1043,
      "message": "Selfie photo is a live photo",
      "score": 0.066661
    }
  },
  "blacklistCheckResult": {
    "faceReferences": [
      {
        "faceId": "bdc41279-d391-4fc9-8d94-972661fae720",
        "matchScore": 1.0
      }
    ]
  }
}