> ## 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 Stateless Verification API

> Capture PhilSys face liveness in a browser and use the returned session with the PhilSys Check API.

## Overview

Integrating PhilSys face liveness requires a 2-step process.

1. **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`.
2. **Call the IDmeta PhilSys Check API using the liveness result**\
   Pass the returned `session_id` as `face_liveness_session_id` in your PhilSys Check request.

## Step 1: Capture PhilSys face liveness

### Prerequisites

Before you integrate the SDK:

* Ask IDmeta for your company Client ID. You use it as `clientId`.
* Ask IDmeta to provision both required company plans:
  * PhilSys Check
  * PhilSys Check Tier 1
* Run the integration in a supported browser with camera access.
* Allow your website's origin in IDmeta's CORS configuration.
* Update your Content Security Policy to allow the required IDmeta and government resources.

### Add the SDK to your website

Load the SDK before you call `IDmetaPhilsysLivenessV3()`:

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

### Start face liveness

```javascript theme={null}
IDmetaPhilsysLivenessV3()
  .start({
    clientId: 'YOUR_COMPANY_CLIENT_ID',
    version: 2
  })
  .then(function (result) {
    console.log(result);
  })
  .catch(function (error) {
    console.error(error);
  });
```

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

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

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

## Step 2: Call the PhilSys Check API

After liveness is completed, pass `result.session_id` as `face_liveness_session_id` in the PhilSys Check API request:

```javascript theme={null}
IDmetaPhilsysLivenessV3()
  .start({
    clientId: 'YOUR_COMPANY_CLIENT_ID',
    version: 2
  })
  .then(function (livenessResult) {
    const faceLivenessSessionId = livenessResult.result.session_id;

    // Add faceLivenessSessionId to your PhilSys Check request as
    // face_liveness_session_id.
    console.log(faceLivenessSessionId);
  });
```

Refer to the API pages for the complete request and response contracts:

* [PhilSys Check Tier 1](/stateless-verification-api/philippines-government/philsys-check-tier-1)

* [PhilSys Check](/stateless-verification-api/philippines-government/philsys-check)

* No bearer token is required.

* The endpoint is limited to 300 requests per minute.

* A valid Client ID alone does not grant access. The company must have both required PhilSys plans.

* The endpoint checks access only. It does not reserve or consume credits.

* The returned public key is used internally to start the government liveness SDK.

The following examples use placeholders. They do not contain a real Client ID, public key, token, identity record, or liveness session.

### Expected Results from Face Liveness Capturing SDK

Completed liveness check

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

Input validation error

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

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

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

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Government liveness unavailable">
    Treat `GOV_SERVER_ERROR` as a temporary government-service outage. Show a retry message and try again later.
  </Accordion>

  <Accordion title="IDmeta network timeout">
    `CLIENT_TIMEOUT` means the IDmeta preflight exceeded the SDK timeout. `NETWORK_ERROR` means the request could not reach IDmeta. Check the device connection, selected version, firewall, and IDmeta service availability.
  </Accordion>

  <Accordion title="CORS error">
    Confirm that your exact website origin, including its scheme and port, is allowed by IDmeta. A CORS failure appears in the browser console and is normalized as `NETWORK_ERROR` when the preflight cannot complete.
  </Accordion>

  <Accordion title="Content Security Policy error">
    Check the browser console for a blocked resource. Update the relevant `script-src`, `connect-src`, `frame-src`, or `img-src` directive for the SDK host, selected IDmeta API origin, and required government origins.
  </Accordion>

  <Accordion title="User cancellation">
    `LIVENESS_CANCELLED` is not a service outage. Let the user restart the capture when they are ready.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup cols={2}>
  <Card title="PhilSys Check Tier 1" icon="braces" href="/stateless-verification-api/philippines-government/philsys-check-tier-1">
    Review the Tier 1 request and response contract.
  </Card>

  <Card title="PhilSys Check" icon="braces" href="/stateless-verification-api/philippines-government/philsys-check">
    Review the PhilSys Check request and response contract.
  </Card>
</CardGroup>