---
title: "Sandbox - PhilSys"
method: POST
path: "/v1/philippines/philsys/sandbox"
tags: ["Sandbox - PhilSys"]
---

# Sandbox - PhilSys

`POST /v1/philippines/philsys/sandbox`

## Request

- Base URL: `https://api.verihubs.com`
- URL: `https://api.verihubs.com/v1/philippines/philsys/sandbox`
- Auth: none declared. Required headers: `App-ID`, `API-Key`

The sandbox for PhilSys Service that enables you to check the response of PhilSys verification without using real data. All validations applied in Live mode are also applied here.

  #### Required inputs
  - `philsys_session_id` — required, a valid UUID. Determines which scenario the transaction returns.
  - `pcn` **or** `pcn_form_data` — required. You must send **exactly one** of the two: sending both, or neither, returns a validation error (`only one of pcn or pcn_form_data must be provided` / `pcn or pcn_form_data is required`).
  - `reference_id` — optional. When it is empty, a random UUID is generated and returned in the response.

  #### Scenario Description
  Scenario       | pcn or pcn_form_data | philsys_session_id         | Result |
  -----------|:---------------------|:---------------------|:-------------------------- |
  VERIFIED | `pcn` = 1234123412341234 <br> or `pcn_form_data` = John / Joseph / Doe / Jr / 01-01-2000 | 0e71f1ed-0000-4000-8000-000000000001 | 200, `verification_status: VERIFIED`, response contains the full identity data |
  REJECTED | `pcn` = 4567456745674567 <br> or `pcn_form_data` = Jonathan / Jovito / Deere / Jr / 10-10-2001 | deac7ed0-0000-4000-8000-000000000002 | 200, `verification_status: REJECTED`, no identity data returned |
  Session ID Not Found | any of the payloads above | 40440400-0000-4000-8000-000000000404 | 400, `philsys_session_id not valid` |
  Liveness Error | `pcn` = 1234123412341234 <br> or the VERIFIED `pcn_form_data` | f01ace00-0000-4000-8000-000000000004 | 400, `verification_status: REJECTED` with the liveness error inside `verification_result` |
  API Error | `pcn` = 1234123412341234 <br> or the VERIFIED `pcn_form_data` | 500e7707-0000-4000-8000-000000000500 | 500, `Internal server error from datasource` |
  Validation Error | {invalid payload, e.g. 15-digit `pcn` or `birth_date` in YYYY-MM-DD} | {any valid UUID} | 400, error message per validated field |

  Use the payload values above so your request matches the documented scenario. `pcn` and `pcn_form_data` are never sent together.

## Headers

- `App-ID` string, required
- `API-Key` string, required

## Request body

- union
  - object
    - `pcn` string, required: 16 digit numeric PhilSys Card Number (PCN). Send this **or** `pcn_form_data`, never both.
    - `pcn_form_data` object: Identity data of the subject. Send this **or** `pcn`, never both.
      - `first_name` string, required: First name, required, maximum 25 characters.
      - `middle_name` string: Middle name, optional, maximum 25 characters.
      - `last_name` string, required: Last name, required, maximum 25 characters.
      - `suffix` string: Name suffix, optional, maximum 10 characters.
      - `birth_date` string, required: Date of birth, required, in DD-MM-YYYY format.
    - `philsys_session_id` string, required: PhilSys session id, required and must be a valid UUID. Determines the sandbox scenario, see the Scenario Description table in the endpoint description.
    - `reference_id` string: Use to indicate your company's transaction. When empty, a random UUID is generated.
  - object
    - `pcn` string: 16 digit numeric PhilSys Card Number (PCN). Send this **or** `pcn_form_data`, never both.
    - `pcn_form_data` object, required: Identity data of the subject. Send this **or** `pcn`, never both.
      - `first_name` string, required: First name, required, maximum 25 characters.
      - `middle_name` string: Middle name, optional, maximum 25 characters.
      - `last_name` string, required: Last name, required, maximum 25 characters.
      - `suffix` string: Name suffix, optional, maximum 10 characters.
      - `birth_date` string, required: Date of birth, required, in DD-MM-YYYY format.
    - `philsys_session_id` string, required: PhilSys session id, required and must be a valid UUID. Determines the sandbox scenario, see the Scenario Description table in the endpoint description.
    - `reference_id` string: Use to indicate your company's transaction. When empty, a random UUID is generated.

## Response `200`

Successful Response

- ResponsePhilSys
  - `id` string, required: Verihubs ID, generated string that is unique for every transaction.
  - `reference_id` string, required: Reference id of the transaction, the same value you sent (or a generated UUID if it was empty).
  - `message` string, required: Shows message of the response.
  - `verification_status` string, required: Verification status of the transaction. Returns `VERIFIED` or `REJECTED`.
  - `verification_result` object: Shows the result of the verification. Scenario VERIFIED returns the identity data: ```json { "data": { "code": "ACR0999", "token": "1000000000000000000000000000000000", "reference": "9876543210123456", "face_url": "https://storage.googleapis.com/image-storage/philsys-face-00000000-0000-4000-8000-000000000001.jpeg", "full_name": "JOHN JOSEPH DOE JR.", "first_name": "JOHN", "middle_name": "JOSEPH", "last_name": "DOE", "suffix": "JR", "gender": "Male", "marital_status": "Single", "blood_type": "O+", "email": "johndoe@sandbox.com", "mobile_number": "6391783929", "birth_date": "2000-01-01", "full_address": "QUEZON CITY, METRO MANILA, PHILIPPINES, 1100", "address_line_1": "BLOCK 1", "address_line_2": null, "barangay": "Loyola Heights", "municipality": "Quezon City", "province": "Metro Manila", "country": "Philippines", "postal_code": "1100", "present_full_address": "MAKATI CITY, METRO MANILA, PHILIPPINES, 1200", "present_address_line_1": "UNIT 303", "present_address_line_2": null, "present_barangay": "Bel-Air", "present_municipality": "Makati", "present_province": "Metro Manila", "present_country": "Philippines", "present_postal_code": "1200", "residency_status": "Resident", "place_of_birth": "MANILA, METRO MANILA", "pob_municipality": "City of Manila", "pob_province": "Metro Manila", "pob_country": "Philippines" }, "meta": { "tier_level": "Tier II", "result_grade": 1 } } ``` Scenario REJECTED returns: ```json { "data": { "verified": false }, "meta": { "tier_level": "Tier II", "result_grade": 0 } } ```
    - `data` object: Identity data of the verified subject, or {"verified": false} when the result is REJECTED.
    - `meta` object: Additional information of the verification result.
      - `tier_level` string: Tier level of the data source.
      - `result_grade` integer: Grade of the verification result.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `429`: Too Many Request
- `500`: Internal Server Error

---

[API](https://skmtc.dev/verihubs/apis/sandbox-philsys-api-documentation.md) - [All operations](https://skmtc.dev/verihubs/apis/sandbox-philsys-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/verihubs/apis/sandbox-philsys-api-documentation/revisions/bfdfa232386a?raw)