Philsys QR Check API

This document outlines the details of the Philsys QR Check API.

API Description

Objective

The Philsys QR Check API processes raw QR code text from various types of QR codes, such as Digital ID, the Philippine Identification System ID (Philsys ID Card), ePhil ID, and National ID Signed and provides structured responses containing relevant details.

Input	Output
Raw QR Code Value	The user's personal information, QR code type, and identity verification data. The complete list of output fields is available in the Success Response Details section.

info

The Philsys QR Check API can process multiple types of Philippine ID QR codes, including Digital ID, Philsys Card, ePhil ID, and National ID Signed formats.

API URL

https://ind-thomas.hyperverge.co/v1/PhilsysQRCheck

API Endpoint

PhilsysQRCheck

Overview

The Philsys QR Check API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Authentication

You need a unique pair of application ID (appId) and application key (appKey) from HyperVerge to verify your identity for accessing the Philsys QR Check API.

API Request Details

Method - POST

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	multipart/form-data
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab.	Not Applicable - this is a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab.	Not Applicable - this is a unique value
transactionId	Mandatory	A unique identifier for tracking a user journey	Not Applicable - this is a unique value related to a transaction in your application

Input

The following table provides the details of the parameter required for the Philsys QR Check API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
value	Mandatory	string	The raw QR code value	A valid QR code string	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Philsys QR Check API:

curl --location --request POST 'https://ind-thomas.hyperverge.co/v1/PhilsysQRCheck' \
--header 'Content-Type: multipart/form-data' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--form 'value="<raw_qr_code_value>"'

Success Response

The following code snippets demonstrate success responses from the Philsys QR Check API for different QR code types:

Digital ID

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "data": {
            "digitalId": "<digital_id>"
        },
        "meta": {
            "qrType": "Digital ID"
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Philsys Card

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "data": {
            "pcn": "<pcn>",
            "firstName": "<first_name>",
            "middleName": "<middle_name>",
            "lastName": "<last_name>",
            "suffix": null,
            "birthDate": "<birth_date>",
            "sex": "<gender>",
            "placeOfBirth": "<place_of_birth>",
            "bestFingerCaptured": [
                "<finger1>",
                "<finger2>"
            ],
            "dateIssued": "<date_issued>",
            "fullName": "<full_name>"
        },
        "meta": {
            "qrType": "Philsys Card"
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

National ID Signed

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "data": {
            "issuer": "<issuer>",
            "version": "<version>",
            "digitalId": "<digital_id>",
            "pcn": "<pcn>",
            "firstName": "<first_name>",
            "lastName": "<last_name>",
            "birthDate": "<birth_date>",
            "issuedAt": "<issued_at>",
            "middleName": "<middle_name>",
            "suffix": null,
            "sex": "<gender>",
            "bloodType": "<blood_type>",
            "maritalStatus": "<marital_status>",
            "placeOfBirth": "<place_of_birth>",
            "bestFingerCaptured": [],
            "photo": "<photo>",
            "fullName": "<full_name>"
        },
        "meta": {
            "qrType": "National ID Signed"
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

ePhilId

{
    "status": "success",
    "statusCode": 200,
    "result": {
        "data": {
            "pcn": "<pcn>",
            "firstName": "<first_name>",
            "middleName": "<middle_name>",
            "lastName": "<last_name>",
            "suffix": null,
            "birthDate": "<birth_date>",
            "sex": "<gender>",
            "placeOfBirth": "<place_of_birth>",
            "bestFingerCaptured": [
                "<finger1>",
                "<finger2>"
            ],
            "dateIssued": "<date_issued>",
            "image": "<image>",
            "fullName": "<full_name>"
        },
        "meta": {
            "qrType": "ePhilId"
        }
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Success Response Details

The following table outlines the details of the success response from the Philsys QR Check API:

Parameter	Type	Description
data	object	Contains the detailed information extracted from the QR code
issuer	string	The issuing authority
version	string	The version of the QR code standard used
digitalId	string	Unique identifier for the user in the digital ID system
pcn	string	Personal Control Number associated with the user
firstName	string	The first name of the user
lastName	string	The last name of the user
birthDate	string	The date of birth of the user
issuedAt	string	The date and time when the ID was issued
middleName	string	The middle name of the user
suffix	string	Any suffix associated with the user's name
sex	string	The gender of the user
bloodType	string	The blood type of the user
maritalStatus	string	The marital status of the user
placeOfBirth	string	The birthplace of the user
bestFingerCaptured	array	List of best-captured finger(s) data for biometrics
photo	string	Base64-encoded image or URL of the user's photo
meta	object	Additional metadata about the QR code
qrType	string	Type of the QR code scanned

Error Responses

The following are some error responses from the Philsys QR Check API:

Missing Value

{
    "status": "failure",
    "statusCode": 400,
    "error": {
        "message": "The value field is required"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Missing/Invalid Credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Invalid Auth

{
    "status": "failure",
    "statusCode": 403,
    "error": "Invalid credentials",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Invalid QR Code

{
    "status": "failure",
    "statusCode": 422,
    "error": {
        "message": "Invalid QR code format"
    },
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Internal Server Error

{
    "status": "failure",
    "statusCode": 500,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Service Unavailable

{
    "status": "failure",
    "statusCode": 503,
    "error": "Internal Server Error",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the Philsys QR Check API contains a failure status with a relevant status code and error message. The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	The value field is required	The request was made with an empty value input	Include a valid QR code string in the value field of the request
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Provide valid appId and appKey in the request headers. Check the dashboard's credentials tab
403	Invalid credentials	The provided credentials do not have access to this API	Contact the HyperVerge team for investigation and resolution
422	Invalid QR code format	The provided QR code value is in an invalid or unsupported format	Verify that the QR code value is a valid Philsys QR code string
500	Internal Server Error	There is an issue with the service. Kindly contact the HyperVerge Team for support.	Contact the HyperVerge team for investigation and resolution
503	Internal Server Error	The external vendor service is temporarily unavailable	Retry the request after some time. If the issue persists, contact the HyperVerge team