> ## Documentation Index
> Fetch the complete documentation index at: https://docs.idmetagroup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```html theme={null}
<script src="https://cdn.portalph.idmetagroup.com/js/philsys-sdk.min.js"></script>
```

Start face liveness:

```javascript theme={null}
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);
  });
```

<Note>
  Your Client ID can be found under *Profile > API Tokens* in your account..
</Note>

### 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

```json theme={null}
{
  "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](https://documenter.getpostman.com/view/46929893/2sB34mhJBq#4407630f-1de3-4110-a6dd-d0081c0ea555).

## Expected API responses

### PhilSys check is successful

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

```json theme={null}
{
  "status": false,
  "message": "OK",
  "response": "{"message": "Server Error"}",
  "api_request_status": 2,
}
```

<Note>
  The `result` field is returned as a stringified JSON value. Parse it first before reading nested fields.
</Note>