Phillipines Philsys Check via API

Validate a Philippine PhilSys Card via API

Overview

Validating a PhilSys Card requires a 2-step process.

1. 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.
2. 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",
    verificationId: "YOUR_VERIFICATION_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
verificationId	IDmeta verification currently running for this session
clientId	You may retrieve your clientId from Profile > API Token page in your Company Admin and Users portal
version	Integer value. Allowed values: 1 or 2. Please confirm with your account manager on the value you should use

Expected Results from Face Liveness Capturing SDK

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

Step 2: Call PhilSys Check API

After the liveness flow is completed, use the liveness session result in your next API call. You can validate using any of these accepted PhilSys input types:

1. PCN
2. Personal information
3. PhilSys card QR value

/api/v1/verification/philippines/philsys

This endpoint validates the entered PhilSys card details together with the captured face liveness to verify authenticity of the document. For request and response details, see the Postman API documentation.

Expected API responses

PhilSys check is successful

{
  "status": 3,
  "status_message": "VERIFIED",
  "message": "PhilSys ID is Valid",
  "result": "{\"data\":{\"code\":\"GMA1234\",\"token\":\"123456789012345678901234567890123456\",\"reference\":\"9876543210987654\",\"face_url\":\"https://example-bucket.s3.ap-southeast-1.amazonaws.com/123/faces/9876543210987654.jpg\",\"full_name\":\"JOHN DOE\",\"first_name\":\"JOHN\",\"middle_name\":\"MICHAEL\",\"last_name\":\"DOE\",\"suffix\":null,\"gender\":\"Male\",\"marital_status\":\"Married\",\"blood_type\":\"O\",\"email\":\"[e-mail]\",\"mobile_number\":\"639123456789\",\"birth_date\":\"1987-01-26\",\"full_address\":\"123 FAKE STREET, SAMPLE BARANGAY, METRO MANILA, PHILIPPINES, 1000\",\"address_line_1\":\"123 FAKE STREET\",\"address_line_2\":null,\"barangay\":\"Sample Barangay\",\"municipality\":\"Quezon City\",\"province\":\"Metro Manila\",\"country\":\"Philippines\",\"postal_code\":\"1000\",\"present_full_address\":\"123 FAKE STREET, SAMPLE BARANGAY, METRO MANILA, PHILIPPINES, 1000\",\"present_address_line_1\":\"123 FAKE STREET\",\"present_address_line_2\":null,\"present_barangay\":\"Sample Barangay\",\"present_municipality\":\"Quezon City\",\"present_province\":\"Metro Manila\",\"present_country\":\"Philippines\",\"present_postal_code\":\"1000\",\"residency_status\":\"Filipino\",\"place_of_birth\":\"MAKATI CITY\",\"pob_municipality\":\"Makati\",\"pob_province\":\"Metro Manila\",\"pob_country\":\"Philippines\"},\"meta\":{\"tier_level\":\"Tier II\",\"result_grade\":1}}"
}

Face liveness ID does not match PCN/QR/form info, or input is invalid

{
  "status": 1,
  "status_message": "REJECTED",
  "message": "Invalid PhilSys ID Information",
  "result": "{\"data\":{\"verified\":false},\"meta\":{\"tier_level\":\"Tier II\",\"result_grade\":2}}"
}

Face liveness ID has expired

{
  "status": 1,
  "status_message": "REJECTED",
  "message": "OK",
  "result": "\"{\\\"error\\\":\\\"face_liveness_error_exception\\\",\\\"message\\\":\\\"Face liveness encountered an error. Please try again.\\\",\\\"error_description\\\":\\\"Face liveness encountered an error. Please try again.\\\"}\""
}

Errors and Issues from eVerify (PSA)

{
  "status": false,
  "message": "OK",
  "response": "{"message": "Server Error"}",
  "api_request_status": 2,
}

The result field is returned as a stringified JSON value. Parse it first before reading nested fields.