Skip to main content

​
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);
  });

​
Liveness options

OptionDescription
verificationIdIDmeta verification currently running for this session
companyUuidYour client/company UUID from your admin profile
versionInteger 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\":\"johndoe@example.com\",\"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.