Phillipines Philsys Check via API

Overview

Validating a PhilSys Card requires a 2-step process.

Face liveness capturing (required by Philippine Statistics Authority (PSA))
This is required before validation. To make implementation simple, include philsys-sdk.min.js to start and handle biometrics liveness capture.
Call IDmeta PhilSys Check API using the liveness result
Use the returned liveness data to call the API and get the validation result for the entered Philsys Information.

Step 1: Philsys Face Liveness Capture

Add this script to your website:

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

Start face liveness:

window.IDmetaPhilsysLiveness()
  .start({
    clientId: "YOUR_CLIENT_ID",
    trustValidationId: "YOUR_TRUST_VALIDATION_ID",
    version: 1
  })
  .then(function (data) {
    console.log("Verification completed successfully", data);
  })
  .catch(function (err) {
    console.error("Verification failed", err);
  });

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

Liveness options

Option	Description
`trustValidationId`	IDmeta Trust Validation currently running for this session. Retrieve it by running the Create Trust Validation API.
`clientId`	You may retrieve your clientId from Profile > API Token page in your Company Admin and Users portal
`version`	Integer value. Use `1` if you are on verify.idmetagroup.com, or `2` if you are on portalph.idmetagroup.com. Or confirm with your account manager.

Step 2: Call PhilSys Check API

After the liveness flow is completed, pass the session_id from the Face Liveness Capturing SDK result as face_liveness_session_id 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:

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

Trust Flows

Custom Forms

Document Verification

Biometric Verification

Internal Blacklists