Philsys QR Check API

The following 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 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 API.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
`content-type`	Mandatory	This parameter defines the media type for the request payload.	application/json
`appId`	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
`appKey`	Mandatory	The application key shared by HyperVerge	Not Applicable - this is a unique value
`transactionId`	Mandatory	The unique ID for the customer 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 API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`value`	Mandatory	The raw QR code value	Valid QR code string	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the 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 API for different QR code types:

Digital ID
Philsys Card
National ID Signed
ePhilId

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

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

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

{
    "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 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

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

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

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

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

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

{
    "status": "failure",
    "statusCode": 503,
    "error": "External source downtime",
    "metaData": {
        "requestId": "<Request_ID>",
        "transactionId": "<Transaction_ID>"
    }
}

Error Response Details

A failure or error response from the module 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
400	The value field is required	This error occurs when we pass empty value as an input
401	Invalid authorization credentials	The request is either missing the mandatory `appId` and `appKey` combination or has invalid values
403	Invalid credentials	Contact HyperVerge for investigation
422	Invalid QR code format	This error occurs when we pass invalid qr code value
500	Internal Server Error	Please check the request headers or contact the HyperVerge team for resolution
503	External source downtime	Please contact the HyperVerge team for resolution

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

API Request Details

Method - POST

Headers

Input​

Request​

Success Response​

Success Response Details​

Error Responses​

Error Response Details​