Guidelines

API Request & Response

Endpoint

This is the regular endpoint that will enable you to verify your client's identity after completing the Liveness process.

MethodURLDescription
POSThttps://api.verihubs.com/philippines/philsys/verifyLive endpoint
POSThttps://api.verihubs.com/philippines/philsys/sandboxSandbox endpoint for scenario testing

Request

Header

KeyTypeNotesDescription
App-IDstringRequiredApplication ID generated in Verihubs Dashboard.
  • Use Production mode in Admin Dashboard to generate live App-ID.
  • Use Sandbox mode in Admin Dashboard to generate sandbox App-ID for scenario testing.
Api-KeystringRequiredAPI-Key connected to the generated App-ID.

Body

Key/ParameterTypeExampleMandatoryDescription
pcn* string 1043321819600133 Yes*16 digits of PCN number as listed on the card.
pcn_form_data*array of string-Yes*

Array that contains names, birth_date and suffix.

No need to input PCN if the user chooses pcn_form_data.

birth_datestring01-01-1970YesIn DD-MM-YYYY format as listed on the card.
first_namestringJuanitoYesFirst name as listed on the card.
middle_namestringReyezYesMiddle name as listed on the card.
last_namestringCruzYesLast name as listed on the card.
suffixstringJr.YesSuffix as listed on the card.
philsys_session_idstringe7b3c294-81fa-4d62-bd57-0a41f692ee13YesRetrieved from the philsys_session_id Liveness SDK response. Will expire in 2 minutes.
reference_idstringUser-Verification-1No

This reference_id can be used to indicate your company’s transaction (must be unique)

Note: If the reference_id is empty or did not include to the request, Verihubs will generate the unique reference_id

Response

HTTP Code

NoCodeDescriptionExamples
1200Successful Transaction; Transaction that is considered successful and has been successfully verified by the data source.

{

    "id": "7c6fcd67-8465-4a8d-9857-03e8f4ac90c8",

    "reference_id": "b25978ff-ffab-4a85-9b71-6786002c7523",

    "message": "PhilSys Check processed successfully",

    "verification_status": "REJECTED",

    "verification_result": {

        "data": {

            "verified": false

        },

        "meta": {

            "tier_level": "Tier II",

            "result_grade": 0

        }

    }

}

2400Liveness Error; Expired philsys_session_id or liveness data retrieval error from Authoritative side (Not charged).

{

    "id": "8d9157fb-55f8-4dbd-a6b5-717dd6ff3dde",

    "reference_id": "Sandbox-Philsys-Not Valid",

    "message": "PhilSys Check processed successfully",

    "verification_status": "REJECTED",

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

    }

}

2400Invalid Payload; Transaction that is considered failed due to validation errors, an error_field will appear explaining the error.

{

    "message": "Invalid payload",

    "error_code": "INVALID_PAYLOAD",

    "error_fields": [

        {

            "fields": "pcn",

            "message": "PCN must be numeric value"

        }

    ]

}

3401Authorization Failed (the transaction cannot proceed because it is unauthorized)

{

    "message": "Authorization failed"

}

4403Quota Insufficient (the transaction failed due to insufficient quota, please contact CS Verihubs)

{

   "message": "Insufficient testing quota",

   "error_code": "FORBIDDEN",

   "error_fields": []

}

5429Too Many Request; Spam Error as the transaction is read as spam, please wait 10 seconds before re-performing the hit process with the same identity.

{

   "message": "Too many request in the allowed time frame",

   "error_code": "TOO_MANY_REQUEST",

   "error_fields": []

}

6500Internal Server Error; The transaction failed due untraced server error that could be caused by data source constraints, timeout, internal error.

{

   "message": "Internal Server Error",

   "error_code": "INTERNAL_SERVER_ERROR"

}

Response Parameter

NoTypeDescriptionExample
messagestringMessage of responsePhilSys check processed successfully
verification_statusstring“VERIFIED” or “REJECTED”VERIFIED
verification_result array of string
  • Lists of personal identity retrieved after VERIFIED transaction.
  • Error details for REJECTED and error transactions.

{

  "data": {

    "code": "ACR0631",

    "token": "2995395506750646662461123444122211",

    "reference": "6103706830790849",

    "face_url": "https://storage.googleapis.com/image-storage/philsys-face-9ce6c061-5b62-4241-adc6-7a91e42304d9.jpeg",

    "full_name": "JUAN DELA CRUZ",

    "first_name": "JUAN",

    "middle_name": "DELA",

    "last_name": "CRUZ",

    "suffix": null,

    "gender": "Female",

    "marital_status": "Single",

    "blood_type": "Unknown",

    "email": "N/A",

    "mobile_number": "630123456789",

    "birth_date": "1998-10-28",

    "full_address": "PAMPANGA, PHILIPPINES, 2005",

    "address_line_1": "PUROK 123",

    "address_line_2": null,

    "barangay": "San Diego",

    "municipality": "Lubao",

    "province": "Pampanga",

    "country": "Philippines",

    "postal_code": "2005",

    "present_full_address": "FULL ADDRESS",

    "present_address_line_1": "PUROK 2",

    "present_address_line_2": null,

    "present_barangay": "San Vicente",

    "present_municipality": "Lubao",

    "present_province": "Pampanga",

    "present_country": "Philippines",

    "present_postal_code": "2005",

    "residency_status": "N/A",

    "place_of_birth": "LUBAO, PAMPANGA",

    "pob_municipality": "Lubao",

    "pob_province": "Pampanga",

    "pob_country": "Philippines"

  },

  "meta": {

    "tier_level": "Tier II",

    "result_grade": 1

  }

}

idstringAutogenerated for every transaction to indicate a unique transaction.9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d
reference_idstringThe ID inputted by the user on request.philsys_f3c0326e-23f7-49d0-8876-71528a860a0d

Sandbox Scenario

The sandbox scenario use dummy input and output to simulate real response from PhilSys. The input is differentiated by its PhilSys Session ID as listed below. All the transaction using Sandbox (Sandbox App-ID & API Key + Sandbox endpoint) is not charged.

ScenarioPhilSys Session IDPayload Example
Verified data.0e71f1ed-0000-4000-8000-000000000001

{

  "pcn": "1234123412341234",

  "pcn_form_data": {

    "birth_date": "01-01-2000",

    "first_name": "John",

    "last_name": "Doe",

    "middle_name": "Joseph",

    "suffix": "Jr"

  },

  "philsys_session_id": "0e71f1ed-0000-4000-8000-000000000001",

  "reference_id": "{input Reference ID}"

}

Rejected data.deac7ed0-0000-4000-8000-000000000002

{

  "pcn": "1234123412341234",

  "pcn_form_data": {

    "birth_date": "01-01-2000",

    "first_name": "John",

    "last_name": "Doe",

    "middle_name": "Joseph",

    "suffix": "Jr"

  },

  "philsys_session_id": "deac7ed0-0000-4000-8000-000000000002",

  "reference_id": "{input Reference ID}"

}

PhilSys Session ID not found.40440400-0000-4000-8000-000000000404

{

  "pcn": "1234123412341234",

  "pcn_form_data": {

    "birth_date": "01-01-2000",

    "first_name": "John",

    "last_name": "Doe",

    "middle_name": "Joseph",

    "suffix": "Jr"

  },

  "philsys_session_id": "40440400-0000-4000-8000-000000000404",

  "reference_id": "{input Reference ID}"

}

Liveness related error (liveness expired, failed to retrieve liveness result).f01ace00-0000-4000-8000-000000000004

{

  "pcn": "1234123412341234",

  "pcn_form_data": {

    "birth_date": "01-01-2000",

    "first_name": "John",

    "last_name": "Doe",

    "middle_name": "Joseph",

    "suffix": "Jr"

  },

  "philsys_session_id": "f01ace00-0000-4000-8000-000000000004",

  "reference_id": "{input Reference ID}"

}

API error.500e7707-0000-4000-8000-000000000500

{

  "pcn": "1234123412341234",

  "pcn_form_data": {

    "birth_date": "01-01-2000",

    "first_name": "John",

    "last_name": "Doe",

    "middle_name": "Joseph",

    "suffix": "Jr"

  },

  "philsys_session_id": "500e7707-0000-4000-8000-000000000500",

  "reference_id": "{input Reference ID}"

}

Updated 11 days ago

Did this page help you?