Phillipines Philsys Check via Stateless Verification API

Overview

Integrating PhilSys face liveness requires a 2-step process.

Capture face liveness with the PhilSys Liveness SDK V3
Start the Philippine government eVerify liveness interface from your website. You provide only clientId and version.
Call the IDmeta PhilSys Check API using the liveness result
Pass the returned session_id as face_liveness_session_id in your PhilSys Check request.

Step 1: Capture PhilSys face liveness

Prerequisites

Before you integrate the SDK:

Ask IDmeta for your company Client ID. You use it as clientId.
Ask IDmeta to provision both required company plans:
- PhilSys Check
- PhilSys Check Tier 1
Run the integration in a supported browser with camera access.
Allow your website’s origin in IDmeta’s CORS configuration.
Update your Content Security Policy to allow the required IDmeta and government resources.

Add the SDK to your website

Load the SDK before you call IDmetaPhilsysLivenessV3():

<script src="https://cdn.portalph.idmetagroup.com/js/philsys-sdk-v3.min.js"></script>

Start face liveness

IDmetaPhilsysLivenessV3()
  .start({
    clientId: 'YOUR_COMPANY_CLIENT_ID',
    version: 2
  })
  .then(function (result) {
    console.log(result);
  })
  .catch(function (error) {
    console.error(error);
  });

Your Client ID can be found under Profile > API Tokens in your account..

Liveness options

Option	Required	Description
`clientId`	Yes	Client ID supplied by IDmeta. The SDK validates its UUID format before making a request.
`version`	No	Integer value. Use `1` if you are on `verify.idmetagroup.com`, or `2` if you are on `portalph.idmetagroup.com`. Confirm with your account manager if you are unsure.

Code	Meaning
`CLIENT_NO_OPTIONS`	`start()` was called without an options object.
`CLIENT_MISSING_PARAMS`	`clientId` is missing or empty.
`BAD_REQUEST`	The Client ID is not a UUID, or the validation service rejected the request as invalid.
`CLIENT_INVALID_VERSION`	`version` is not `1` or `2`.
`INVALID_COMPANY`	The Client ID is a valid UUID but does not identify an IDmeta company.
`PLAN_ACCESS_DENIED`	The company is missing `scan_qr`, `philsys_check_tier_1`, or both plans.
`RATE_LIMITED`	The preflight request exceeded the rate limit. Wait before retrying.
`SERVER_ERROR`	The IDmeta validation service returned a server error.
`HTTP_<status>`	The IDmeta validation service returned another unexpected HTTP status.
`SERVER_NO_PUBKEY`	Access validation succeeded, but the response did not contain the government public key.
`CLIENT_TIMEOUT`	The IDmeta preflight did not complete within the SDK timeout.
`NETWORK_ERROR`	The browser could not reach the IDmeta validation service.
`LIVENESS_CANCELLED`	The user closed or aborted the capture before it completed.
`GOV_SERVER_ERROR`	The government SDK or its infrastructure was unavailable.
`LIVENESS_FAILED`	The government liveness flow started but could not complete normally.

LIVENESS_CANCELLED means the user closed the capture. LIVENESS_FAILED means the government flow ran but could not complete normally. GOV_SERVER_ERROR represents a government SDK or infrastructure outage. NETWORK_ERROR means the IDmeta preflight could not be reached.

Step 2: Call the PhilSys Check API

After liveness is completed, pass result.session_id as face_liveness_session_id in the PhilSys Check API request:

IDmetaPhilsysLivenessV3()
  .start({
    clientId: 'YOUR_COMPANY_CLIENT_ID',
    version: 2
  })
  .then(function (livenessResult) {
    const faceLivenessSessionId = livenessResult.result.session_id;

    // Add faceLivenessSessionId to your PhilSys Check request as
    // face_liveness_session_id.
    console.log(faceLivenessSessionId);
  });

Refer to the API pages for the complete request and response contracts:

PhilSys Check Tier 1
PhilSys Check
No bearer token is required.
The endpoint is limited to 300 requests per minute.
A valid Client ID alone does not grant access. The company must have both required PhilSys plans.
The endpoint checks access only. It does not reserve or consume credits.
The returned public key is used internally to start the government liveness SDK.

The following examples use placeholders. They do not contain a real Client ID, public key, token, identity record, or liveness session.

Expected Results from Face Liveness Capturing SDK

Completed liveness check

{
  "status": "COMPLETED",
  "result": {
    "photo": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAA...",
    "session_id": "a1b3fae6-af74-4896-bd58-32a81604de01",
    "photo_url": "https://liveness.photo.url/image.jpg/?expires=some-expiration"
  }
}

Input validation error

{
  "status": "BAD_REQUEST",
  "message": "Validation failed",
  "errors": {
    "clientId": ["The client id field is required."],
    "trustValidationId": ["The trust validation id field is required."]
  }
}

Invalid Trust Validation and Client ID combination

{
  "status": "BAD_REQUEST",
  "message": "The Client ID or Trust Validation ID is incorrect. Please double-check the values.",
  "trustValidationId": "trust_validation_id"
}

Capture session closed before completion

{
  "status": "ERROR",
  "code": "LIVENESS_CANCELLED",
  "message": "The liveness check was closed before it finished. Please start the capture again to complete your verification."
}

Unreachable government site

{
  "status": "ERROR",
  "code": "GOV_SERVER_ERROR",
  "message": "The PhilSys verification service is currently unavailable. This is a problem on the government side, not with your details. Please try again in a few minutes."
}

Troubleshooting

Invalid Client ID

Confirm that clientId is the company UUID supplied by IDmeta. Remove leading or trailing spaces. A value that is not a UUID is rejected locally with BAD_REQUEST. An unknown UUID is rejected with INVALID_COMPANY.

Missing PhilSys plan access

Ask IDmeta to provision both scan_qr and philsys_check_tier_1 for your company. The SDK returns PLAN_ACCESS_DENIED if either plan is missing.

Camera permission denied

Ask the user to allow camera access for your site in the browser settings, then restart the capture. Confirm that the page uses HTTPS in production.

Government liveness unavailable

Treat GOV_SERVER_ERROR as a temporary government-service outage. Show a retry message and try again later.

IDmeta network timeout

CLIENT_TIMEOUT means the IDmeta preflight exceeded the SDK timeout. NETWORK_ERROR means the request could not reach IDmeta. Check the device connection, selected version, firewall, and IDmeta service availability.

CORS error

Confirm that your exact website origin, including its scheme and port, is allowed by IDmeta. A CORS failure appears in the browser console and is normalized as NETWORK_ERROR when the preflight cannot complete.

Content Security Policy error

Check the browser console for a blocked resource. Update the relevant script-src, connect-src, frame-src, or img-src directive for the SDK host, selected IDmeta API origin, and required government origins.

User cancellation

LIVENESS_CANCELLED is not a service outage. Let the user restart the capture when they are ready.

Trust Flows

Custom Forms

Document Verification

Biometric Verification

Internal Blacklists

Philippines Philsys Check

Data Types

Data handling and privacy

Phillipines Philsys Check via Stateless Verification API

Overview

Step 1: Capture PhilSys face liveness

Prerequisites

Add the SDK to your website

Start face liveness

Liveness options

Step 2: Call the PhilSys Check API

Expected Results from Face Liveness Capturing SDK

Troubleshooting

Next steps

PhilSys Check Tier 1

PhilSys Check

​Overview

​Step 1: Capture PhilSys face liveness

​Prerequisites

​Add the SDK to your website

​Start face liveness

​Liveness options

​Step 2: Call the PhilSys Check API

​Expected Results from Face Liveness Capturing SDK

​Troubleshooting

​Next steps

PhilSys Check Tier 1

PhilSys Check

Overview

Step 1: Capture PhilSys face liveness

Prerequisites

Add the SDK to your website

Start face liveness

Liveness options

Step 2: Call the PhilSys Check API

Expected Results from Face Liveness Capturing SDK

Troubleshooting

Next steps