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 faceLivenessSessionId in your PhilSys Check request.

Step 1: Capture PhilSys face liveness

Add the SDK to your website

Load the SDK before you call IDmetaPhilsysLivenessV3():

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

Start face liveness

IDmetaPhilsysLiveness()
  .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.

Liveness Result Statuses

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.

Sample 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."]
  }
}

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."
}

Step 2: Call PhilSys Check API

After the liveness flow is completed, pass the session_id from the Face Liveness Capturing SDK result as faceLivenessSessionId in your PhilSys Check API request. You can validate using any of these accepted PhilSys input types:

PCN
Personal information
PhilSys card QR value

Refer to the individual API pages for request and response details:

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.

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

Document Verification V2

Biometric Verification

Internal Blacklists

Philippines Philsys Check

Data Types

Data handling and privacy

Stateless API Sandbox

Phillipines Philsys Check via Stateless Verification API

Overview

Step 1: Capture PhilSys face liveness

Add the SDK to your website

Start face liveness

Liveness Options

Liveness Result Statuses

Sample Results from Face Liveness Capturing SDK

Step 2: Call PhilSys Check API

Troubleshooting

Next steps

PhilSys Check Tier 1

PhilSys Check Tier 2

​Overview

​Step 1: Capture PhilSys face liveness

​Add the SDK to your website

​Start face liveness

​Liveness Options

​Liveness Result Statuses

​Sample Results from Face Liveness Capturing SDK

​Step 2: Call PhilSys Check API

​Troubleshooting

​Next steps

PhilSys Check Tier 1

PhilSys Check Tier 2

Overview

Step 1: Capture PhilSys face liveness

Add the SDK to your website

Start face liveness

Liveness Options

Liveness Result Statuses

Sample Results from Face Liveness Capturing SDK

Step 2: Call PhilSys Check API

Troubleshooting

Next steps