OCR Lite

Note : Please first check the Glossary for basic information about ADVANCE API.

Code Sample: UMID

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: multipart/form-data" \
-F "ocrImage=@/Users/lby/Desktop/ocrImage.jpg" \
-F "cardType=UMID" \
"https://ph-api.advance.ai/ph/openapi/face-identity/v5/ocr-lite"

Code Sample: SSS

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: multipart/form-data" \
-F "ocrImage=@/Users/lby/Desktop/ocrImage.jpg" \
-F "cardType=SSS" \
"https://ph-api.advance.ai/ph/openapi/face-identity/v5/ocr-lite"

Code Sample: cardType is null

curl -X POST \
-H "X-ACCESS-TOKEN: {Your Access Token}" \
-H "Content-Type: multipart/form-data" \
-F "ocrImage=@/Users/lby/Desktop/ocrImage.jpg" \
"https://ph-api.advance.ai/ph/openapi/face-identity/v5/ocr-lite"

Request URL

https://ph-api.advance.ai/ph/openapi/face-identity/v5/ocr-lite
POST (form-data)

Notes:

ADVANCE service is deployed overseas. If your test/official environment is with Internet restrict, please request the service via VPN to avoid packet loss, service timeout and other problems

Request Header Parameters:

Parameter	Description
X-ACCESS-TOKEN	`string` Please Click here to get your access token

Request Parameters:

Parameter	Description
ocrImage	`file` image of a card
cardType	`string` `optional` type of card, the cardType should be `UMID` or `SSS` or `TIN` or `PASSPORT` or `VOTERID` or `NATIONALID` or `E_NATIONALID_V1` or `E_NATIONALID_V2` or `PRC` or `PAGIBIG` or `POSTALID` or `DRIVINGLICENSE` or `HEALTHCARD` or `GSIS` otherwise, we will return `PARAMETER_ERROR`

Note:
- Please check the OCR image quality requirements in the Glossary to ensure that OCR would work properly;

Example of Success Response when CardType is UMID (New version):

   {
    "code":"SUCCESS",
    "message":"OK",
    "data":{
          "result":{
                "idNumber":"0000-4444444-4",
                "surname":"MMMMMMMM",
                "middleName":"EEEEEEEE",
                "givenName":"AAAA",
                "birthday":"1987/11/08",
                "birthdayParsed": "1987/11/08",
                "gender":"F",
                "postcode":"4444",
                "ph":"PHL",
                "province":"LLLLLL",
                "city":"SSSSS RRRR",
                "homeAddress":"BBB 00 LLL 00 CCCCCCC ST. AAAAAAA HHHHH II BBBB. SSSSSSSS SSSSS RRRR CCCC LLLLLL",
                "fullAddress":"BBB 00 LLL 00 CCCCCCC ST. AAAAAAA HHHHH II BBBB. SSSSSSSS SSSSS RRRR CCCC LLLLLL PHL 4444"
            },
            "cardSide":"front",
            "cardType":"UMID"
    },
    "extra":null,
    "transactionId":"77da92bbb624c805",
    "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is UMID (Old version):

   {
    "code":"SUCCESS",
    "message":"OK",
    "data":{
        "result":{
            "birthday":"1975/05/01",
            "gender":"FEMALE",
            "city":"DAET",
            "givenName":"G****A",
            "postcode":"4600",
            "birthdayParsed":"1975/05/01",
            "idNumber":"0111-4*****9-0",
            "province":"CAMARINES NORTE",
            "surname":"A*****A",
            "fullAddress":"P-6 M******S I***A C*****N DAET CA*****S NORTE PHL 4600",
            "ph":"PHL",
            "middleName":"C**O",
            "homeAddress":"P-6 M*****ES I***A CA*****N DAET CA*****ES NORTE"
        },
        "cardSide":"front",
        "cardType":"UMID"
      },
    "extra":null,
    "transactionId":"3770440f6c3af005",
    "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is SSS:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"OCTOBER 28,1977",
                "name":"R****N Q****L S***O",
                "birthdayParsed":"1977/10/28",
                "idNumber":"09-1*****7-1"
              },
            "cardSide":"front",
            "cardType":"SSS"
        },
        "extra":null,
        "transactionId":"f66f9ce83d742c32",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is TIN:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"10-FEB-1985",
                "address":"C*****D SQUARE P M***A STREET B**Y PIO DEL P****R M****I CITY",
                "documentNumber":"TCD20*******5",
                "birthdayParsed":"1985/02/10",
                "name":"P***Z G***N S***A",
                "issuerAuthority":"044-20****5",
                "idNumber":"2*3-7*1-3*1-00000",
                "issueDate":"11-FEB-2022",
                "issueDateParsed":"2022/02/11"
                },
             "cardSide":"front",
            "cardType":"TIN"
          },
        "extra":null,
        "transactionId":"fa609769fb4fd736",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is PASSPORT:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"15 DEC 90",
                "gender":"F",
                "surName":"L*****O",
                "givenName":"P****S S A**E",
                "birthdayParsed":"1990/12/15",
                "idNumber":"EC0*****0",
                "type":"P",
                "expiryDateParsed":"2019/02/26",
                "expiryDate":"26 FEB 19",
                "birthPlace":"M****I MM",
                "issuingAuthority":"D*****I MM ",
                "nationality":"F*****O",
                "countryCode":"PHL",
                "middleName":"M*****O",
                "issueDate":"27 FEB 14",
                "issueDateParsed":"2014/02/27"
            },
            "cardSide":"front",
            "cardType":"PASSPORT"
        },
        "extra":null,
        "transactionId":"84a5d369caf71465",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is DRIVINGLICENSE:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"1978/11/29",
                "address":"128 S*****K ST. S***N,A*****Y,B****N",
                "gender":"F",
                "birthdayParsed":"1978/11/29",
                "restrictions":"1,2",
                "weight":"49",
                "agencyCode":"B*C",
                "bloodType":"A+",
                "idNumber":"C02-18-0****4",
                "expiryDateParsed":"2022/11/29",
                "assistantSecretary":"E****R C. G*****E",
                "expiryDate":"2022/11/29",
                "eyeColor":"BLACK",
                "nationality":"PHL",
                "name":"M****S,C****A C*****S",
                "conditions":"NONE",
                "height":"1.55"
            },
            "cardSide":"front",
            "cardType":"DRIVINGLICENSE"
        },
        "extra":null,
        "transactionId":"aca7628d47d0cefa",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is NATIONALID and cardSide is front:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"",
                "firstName":"S**A,C**U CITY D**E OF B***H OCTOBER 09,1988 DATE OF ISSUE SEPTEMBER 12,2011",
                "lastName":"R***N,R***N S****NO",
                "birthdayParsed":null,
                "fullAddress":"",
                "middleName":"S*****E",
                "idNumber":"4*2-7*3-8*9-0*0 4-53 A*****A ST"
            },
            "cardSide":"front",
            "cardType":"NATIONALID"
        },
        "extra":null,
        "transactionId":"b895b8f558699dc0",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is NATIONALID and cardSide is back:

{
    "code":"SUCCESS",
    "data":{
        "result":{
            "birthPlace":"****,****** *****",
            "gender":"FEMALE",
            "documentNumber":"**********",
            "bloodType":"UNKNOWN",
            "issueDate":"26 MARCH 2022",
            "issueDateParsed":"2022/03/26",
            "maritalStatus":"SINGLE"
        },
        "cardSide":"back",
        "cardType":"NATIONALID"
    },
    "extra":null,
    "pricingStrategy":"PAY",
    "message":"OK",
    "transactionId":"0fd694facf20e980"
}

Example of Success Response when CardType is E_NATIONALID_V1 and cardSide is front:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
        "result":{
            "firstName":"MARIANNE CASSANDRA",
            "lastName":"VARQUEZ",
            "middleName":"REQUITILLO",
            "idNumber":"****-****-****-****"
        },
        "cardSide":"front",
        "cardType":"E_NATIONALID_V1"
    },
    "pricingStrategy":"PAY",
    "extra":null,
    "transactionId":"471fad3d54f89abd"
}

Example of Success Response when CardType is E_NATIONALID_V1 and cardSide is back:

{
    "code":"SUCCESS",
    "data":{
        "result":{
            "birthday":"DECEMBER 03, 2001",
            "birthPlace":"CITY OF CEBU,CEBU",
            "address":"***** ******,****** ******",
            "gender":"FEMALE",
            "birthdayParsed":"2001/12/03",
            "bloodType":"O-",
            "issueDate":"13 FEBRUARY 2023",
            "issueDateParsed":"2023/02/13",
            "maritalStatus":"SINGLE"
        },
        "cardSide":"back",
        "cardType":"E_NATIONALID_V1"
    },
    "extra":null,
    "pricingStrategy":"PAY",
    "message":"OK",
    "transactionId":"6201525e16cfe7ab"
}

Example of Success Response when CardType is E_NATIONALID_V2 and cardSide is front:

{
    "code":"SUCCESS",
    "data":{
        "result":{
            "birthday":"APRIL 28, 1998",
            "firstName":"********",
            "lastName":"********",
            "birthdayParsed":"1998/04/28",
            "fullAddress":"********,********,********,********,********",
            "middleName":"********",
            "idNumber":"****-****-****-****"
        },
        "cardSide":"front",
        "cardType":"E_NATIONALID_V2"
    },
    "extra":null,
    "pricingStrategy":"PAY",
    "message":"OK",
    "transactionId":"24bd67325b53ef22"
}

Example of Success Response when CardType is E_NATIONALID_V2 and cardSide is back:

{
    "code":"SUCCESS",
    "data":{
        "result":{
            "birthPlace":"**** **** **** **** ****",
            "gender":"FEMALE",
            "bloodType":"B",
            "idNumber":"****",
            "maritalStatus":"SINGLE"
        },
        "cardSide":"back",
        "cardType":"E_NATIONALID_V2"
    },
    "extra":null,
    "pricingStrategy":"PAY",
    "message":"OK",
    "transactionId":"a6dd19b16306ef37"
}

Example of Success Response when CardType is PAGIBIG:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
        "result":{
            "fullName":"DONNIVER V AGNES",
            "idNumber":"*****-*****-*****"
        },
        "cardSide":"front",
        "cardType":"PAGIBIG"
    },
    "extra":null,
    "transactionId":"75b9b85e245f77f0",
    "pricingStrategy":"PAY"
}

Example of Success Response when CardType is POSTALID:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"08 FEB 99",
                "expiryDate":"30 JUN 20",
                "nationality":"PHL",
                "birthdayParsed":"1999/02/08",
                "fullAddress":"L31 V*****E R****Y M****O 2 1**4 LAS P***S CITY N.CR",
                "fullName":"R**E A*N S**A",
                "issuerAuthority":"RLP.LP",
                "expiryDateParsed":"2020/06/30",
                "idNumber":"N35********8"
            },
            "cardSide":"front",
            "cardType":"POSTALID"
        },
        "extra":null,
        "transactionId":"77fc58f67e0c6425",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is PRC:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "expiryDate":"11/03/2022",
                "firstName":"A***A M*E",
                "lastName":"A*****N",
                "occupation":"M****L T*****T",
                "middleName":"R****A",
                "expiryDateParsed":"2022/11/03",
                "idNumber":"0*****3",
                "issueDate":"04/04/2016",
                "issueDateParsed":"2016/04/04"
            },
            "cardSide":"front",            
            "cardType":"PRC"
        },
        "extra":null,
        "transactionId":"c56d340f1645754e",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is VOTERID:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"JANUARY 31,1994",
                "precinctNo":"0***B",
                "nationality":"F*****O",
                "birthdayParsed":"1994/01/31",
                "fullAddress":"I***A,D***A-AN",
                "fullName":"V**O J**N C***O P****O",
                "chairman":"S****O S. B*****S,JR.",
                "idNumber":"7**1-0**1B-A3**4JPV1***0",
                "civilStatus":"SINGLE"
            },
            "cardSide":"front",
            "cardType":"VOTERID "
        },
        "extra":null,
        "transactionId":"f911beb38526d5b1",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is HEALTHCARD:

   {
        "code":"SUCCESS",
        "message":"OK",
        "data":{
            "result":{
                "birthday":"JULY 31, 1998",
                "birthdayParsed":"1998/07/31",
                "fullAddress":"L31 V*****E R****Y M****O 2 1**4 LAS P***S CITY N.CR",
                "fullName":"LIOOT, ANDYOO",
                "gender":"MALE",
                "idNumber":"01-200000000-00"
            },
            "cardSide":"front",
            "cardType":"HEALTHCARD "
        },
        "extra":null,
        "transactionId":"f911beb38526d5b1",
        "pricingStrategy":"PAY"
   }

Example of Success Response when CardType is GSIS:


{
    "code":"SUCCESS",
    "data":{
        "result":{
            "birthday":"06/23/1991",
            "crnNumber":"109585051227",
            "address":"BGY BURIRAO NARRA PALAWAN PHL 5303",
            "bankCardNumber":"4162980231834044",
            "validDate":"07/26",
            "birthdayParsed":"1991/06/23",
            "name":"ERLYN E. ABREA",
            "idNumber":"02005646563"
        },
        "cardSide":"front",
        "cardType":"GSIS"
    },
    "extra":null,
    "pricingStrategy":"PAY",
    "message":"OK",
    "transactionId":"038fd391886d339f"
}

Example OCR_NO_RESULT Response:

{
    "code":"OCR_NO_RESULT",
    "message":"OCR check failed,unable to find any available field in the uploaded picture",
    "data":{
        "result":null,
        "cardType":null
    },
    "extra":null,
    "transactionId":"7c85015b4a592448",
    "pricingStrategy":"PAY"
}

Example CARD_TYPE_NOT_MATCH Response:

{
    "code":"CARD_TYPE_NOT_MATCH",
    "message":"The card type is not match",
    "data":null,
    "extra":null,
    "transactionId":"867e9cfab23f0ae3",
    "pricingStrategy":"PAY"
}

Example of PARAMETER_ERROR Response:


{
    "code":"PARAMETER_ERROR",
    "message":"Parameter error, please check your input.",
    "data":null,
    "extra":null,
    "transactionId":"27804f483884db31",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"c580b87c0bd4e885",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Invalid image format,image format should be one of jpeg/jpg/png,and request content type should be image/jpeg or image/png",
    "data":null,
    "extra":null,
    "transactionId":"fbca3dcac683ec48",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Invalid image size,max image size should be less than 2M,and image dimension should be between 256 * 256 and 4096 * 4096",
    "data":null,
    "extra":null,
    "transactionId":"8fddbb228fd8313d",
    "pricingStrategy":"FREE"
}

Response Description:

Parameter	Description
code	OCR Status Code
transactionId	The request id, the max length is 64
pricingStrategy	Whether the request will be charged, enum type: `FREE`, `PAY`
message	Status Code Explanation
data	`result` : The result detail,click here for the Detail of this JSON object
	`cardType` : The cardType value should be `UMID`, `SSS`, `TIN`, `PASSPORT`, `VOTERID`, `NATIONALID`,`E_NATIONALID_V1`,`E_NATIONALID_V2`, `PRC`, `PAGIBIG`, `POSTALID`, `DRIVINGLICENSE`,`HEALTHCARD`,`GSIS`
	`cardSide` : `front` or `back`
extra	Extra response info (Exception Message)

Note：When parsing the cardType field, please don’t limit to the service’s response, as we will support more card types in the future depending on customer requirements.

Result Detail When CardType Is UMID:

Field Name	Description
`birthday`	`string` Date of birth of the person, for example “1986/04/08”,this field shows the raw recognized results without any modifications
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`gender`	`string` Gender of the person
`idNumber`	`string` ID number of the person, for example “006-0041-5476-5”
`surname`	`string` Surname of the person
`middleName`	`string` Middle name of the person
`givenName`	`string` Given name of the person
`postcode`	`string` Postcode of the address
`ph`	`string` PHI or PHL
`province`	`string` Province in the address
`city`	`string` City in the address
`homeAddress`	`string` Home address of the person
`fullAddress`	`string` Full address of the person

Result Detail When CardType Is SSS:

Field Name	Description
`birthday`	`string` Date of birth of the person, for example “DECEMBER 6,1965”,this field shows the raw recognized results without any modifications
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`name`	`string` Name of the person
`idNumber`	`string` ID number of the person, for example “03-7206344-5”

Result Detail When CardType Is TIN:

Field Name	Description
`birthday`	`string` Date of birth of the person, for example “03-09-1986”,this field shows the raw recognized results without any modifications
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`issueDate`	`string` Issue date of the card, for example “03-26-2019”,this field shows the raw recognized results without any modifications
`issueDateParsed`	`string` The parsed issue date of the card, the format is YYYY/MM/DD,this field, instead of field issueDate, is more suggested to be referred to
`name`	`string` Name of the person
`address`	`string` Address of the person
`idNumber`	`string` ID number of the person, for example “275-855-533-000”
`documentNumber`	`string` The document number of the card
`issuerAuthority`	`string` Document issuer Authority

Result Detail When CardType Is PASSPORT:

Field Name	Description
`birthday`	`string` Date of birth of the person, for example, “15 DEC 87”,this field shows the raw recognized results without any modifications
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD;this field, instead of field birthday, is more suggested to be referred to
`surName`	`string` Surname of the person
`gender`	`string` Gender of the person
`givenName`	`string` Given name of the person
`idNumber`	`string` ID number of the person, for example, “P1085120A”
`type`	`string` Type of the passport
`expiryDate`	`string` Expiry date of the passport,this field shows the raw recognized results without any modifications
`expiryDateParsed`	`string` The parsed expiry date of the card, the format is YYYY/MM/DD; this field, instead of field expiryDate, is more suggested to be referred to
`birthPlace`	`string` Birthplace of the person
`issuingAuthority`	`string` Issuing authority of the passport
`nationality`	`string` Nationality of the person
`countryCode`	`string` Country code of the person
`middleName`	`string` Middle name of the person
`issueDate`	`string` Issue date of the card, for example “03-26-2019”,this field shows the raw recognized results without any modifications
`issueDateParsed`	`string` The parsed issue date of the card, the format is YYYY/MM/DD,this field, instead of field issueDate, is more suggested to be referred to

Result Detail When CardType Is DRIVINGLICENSE:

Field Name	Description
`birthday`	`string`Date of birth of the person,this field shows the raw recognized results without any modifications
`birthdayParsed`	`string`The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`address`	`string` Address of the person
`gender`	`string` Gender of the person
`weight`	`string` Weight of the person
`restrictions`	`string` Restrictions of the vehicle type
`agencyCode`	`string` Agency code of the issuing office
`idNumber`	`string` ID number of the person, for example, “C02-11-002230”
`bloodType`	`string` Blood type of person
`assistantSecretary`	`string` Assistant secretary of the driving license
`expiryDate`	`string` Expiry date of the driving license,this field shows the raw recognized results without any modifications
`expiryDateParsed`	`string` The parsed expiry date of the card, the format is YYYY/MM/DD; this field, instead of field expiryDate, is more suggested to be referred to
`nationality`	`string` Nationality of the person
`eyeColor`	`string` Eye color of the person
`name`	`string` Name of the person
`conditions`	`string` Conditions of the person
`height`	`string` Height of the person

Result Detail When CardType Is NATIONALID and cardSide is front:

Field Name	Description
`birthday`	`string` The birthday of the person
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`firstName`	`string` The first name of the person
`lastName`	`string` The last name of the person
`middleName`	`string` The middle name of the person
`fullAddress`	`string` The address of the person
`idNumber`	`string` The ID number of the person

Result Detail When CardType Is NATIONALID and cardSide is back:

Field Name	Description
`birthPlace`	`string` Birthplace of the person
`gender`	`string` Gender of the person
`documentNumber`	`string` The document number of the card
`bloodType`	`string` Blood type of person
`issueDate`	`string` The issue date of the card
`issueDateParsed`	`string` The parsed issue date of the card, the format is YYYY/MM/DD,this field, instead of field issueDate, is more suggested to be referred to
`maritalStatus`	`string` The marital status of the person

Result Detail When CardType Is E_NATIONALID_V1 and cardSide is front:

Field Name	Description
`firstName`	`string` The first name of the person
`lastName`	`string` The last name of the person
`middleName`	`string` The middle name of the person
`idNumber`	`string` The ID number of the person

Result Detail When CardType Is E_NATIONALID_V1 and cardSide is back:

Field Name	Description
`birthday`	`string` The birthday of the person
`birthPlace`	`string` Birthplace of the person
`address`	`string` Address of the person
`gender`	`string` Gender of the person
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`bloodType`	`string` Blood type of person
`issueDate`	`string` The issue date of the card
`issueDateParsed`	`string` The parsed issue date of the card, the format is YYYY/MM/DD,this field, instead of field issueDate, is more suggested to be referred to
`maritalStatus`	`string` The marital status of the person

Result Detail When CardType Is E_NATIONALID_V2 and cardSide is front:

Field Name	Description
`firstName`	`string` The first name of the person
`lastName`	`string` The last name of the person
`middleName`	`string` The middle name of the person
`idNumber`	`string` The ID number of the person
`fullAddress`	`string` The address of the person
`birthday`	`string` The birthday of the person
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to

Result Detail When CardType Is E_NATIONALID_V2 and cardSide is back:

Field Name	Description
`birthPlace`	`string` Birthplace of the person
`gender`	`string` Gender of the person
`bloodType`	`string` Blood type of person
`idNumber`	`string` The ID number of the person
`maritalStatus`	`string` The marital status of the person

Result Detail When CardType Is PRC:

Field Name	Description
`expiryDate`	`string` The expiry date of the card
`idNumber`	`string` The ID number of the person
`firstName`	`string` The first name of the person
`lastName`	`string` The last name of the person
`middleName`	`string` The middle name of the person
`occupation`	`string` The occupation of the person
`expiryDateParsed`	`string` The parsed expiry date of the card, the format is YYYY/MM/DD; this field, instead of field expiryDate, is more suggested to be referred to
`issueDate`	`string` The issue date of the card
`issueDateParsed`	`string` The parsed issue date of the card, the format is YYYY/MM/DD,this field, instead of field issueDate, is more suggested to be referred to

Result Detail When CardType Is PAGIBIG:

Field Name	Description
`fullName`	`string` The full name of the person
`idNumber`	`string` The ID number of the person

Result Detail When CardType Is POSTALID:

Field Name	Description
`birthday`	`string` The birthday of the person
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`issuerAuthority`	`string` Document issuer Authority
`expiryDateParsed`	`string` The parsed expiry date of the card, the format is YYYY/MM/DD; this field, instead of field expiryDate, is more suggested to be referred to
`fullName`	`string` The full name of the person
`expiryDate`	`string` The expiry date of the card
`idNumber`	`string` The ID number of the person
`fullAddress`	`string` The address of the person
`nationality`	`string` Document holder nationality

Result Detail When CardType Is VOTERID:

Field Name	Description
`birthday`	`string` The birthday of the person
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`precinctNo`	`string` Number of precinct
`civilStatus`	`string` Civil status of the person
`fullName`	`string` The full name of the person
`chairman`	`string` Chairman of the Card
`idNumber`	`string` The ID number of the person
`fullAddress`	`string` The address of the person
`nationality`	`string` Document holder nationality

Result Detail When CardType Is HEALTHCARD:

Field Name	Description
`birthday`	`string` The birthday of the person
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`fullName`	`string` The full name of the person
`gender`	`string` Gender of the person
`idNumber`	`string` The ID number of the person
`fullAddress`	`string` The address of the person

Result Detail When CardType Is GSIS:

Field Name	Description
`name`	`string` Name of the person
`birthday`	`string` Date of birth of the person, for example “03-09-1986”,this field shows the raw recognized results without any modifications
`birthdayParsed`	`string` The parsed birthday of the person, the format is YYYY/MM/DD; this field, instead of field birthday, is more suggested to be referred to
`address`	`string` Address of the person
`bankCardNumber`	`string` The card number is usually a bank account number associated with one of the two banks, UnionBank of the Philippines or Land Bank of the Philippines, and is mainly used for social security and pension services for government employees.
`validDate`	`string` Card expiry date
`idNumber`	`string` ID number of the person, for example “275-855-533-000”
`crnNumber`	`string` CRN number refers to “Common Reference Number”. Itis a unique number assigned by the Philippine government to each GSIS member and is used to identify individuals in different government service systems.

Response Code

Status Code	Message
`OCR_NO_RESULT`	`pay` OCR check failed, unable to find any available field in the uploaded picture
`CARD_TYPE_NOT_MATCH`	`pay` The card type is not match

Note: Please remember to add a handler for the Status Codes in the Glossary as well

Token Authentication

Request Parameters:

Parameter	Description
accessKey	`string` the accessKey
timestamp	`string` 13-digit-long timestamp, suggested 300 seconds before or after the current time when requesting the token
signature	`string` Combined accessKey, secretKey and timestamp, encrypted by SHA256. eg. accessKey: sampleaccesskey secretKey: samplesecretkey timestamp: 1665993522952 Combined: sampleaccesskeysamplesecretkey1665993522952 Encrypted based on the combined: 02209bbeaf0d0a3dd587f6a1ba22f84c98d142e3b545e77db7e4906ca56349f5
periodSecond	`string` `optional` Validity period defaults to 3600 seconds, minimum 60 seconds, maximum 86400 seconds. Unit is seconds

Note:

You can find accessKey, secretKey on the Websaas Platform -> Account -> Account Management
The timestamp in the “signature” must be consistent with parameter timestamp
Please remember to re-obtain a new valid token to do the authentication for the open APIs when the previous one is expired

Code Sample

curl -X POST \
-H "Content-Type: application/json" \
-d '{"accessKey":"22********70b","signature":"f786441e7b3d95f*****************853a5a244f9522","timestamp":1648785145789,"periodSecond":120}' \ 
"https://ph-api.advance.ai/openapi/auth/ticket/v1/generate-token"

Request Url

https://ph-api.advance.ai/openapi/auth/ticket/v1/generate-token
POST (application/json)

Notes:

ADVANCE service is deployed overseas. If your test/official environment is with Internet restrictions, please request the service via VPN to avoid packet loss, service timeout and other problems

Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
    "token":"eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJoNV9saXZlbmVzcyIsInN1YiI6IntcImN1c3RvbWVySWRcIjo1NTAwMDI4MixcImFjY291bnRJZFwiOjU1MDAwMjg0LFwicmVhbElwXCI6XCI0NS4yNTEuMTA3LjExMVwifSIsImF1ZCI6IldFQiIsImlhdCI6MTY0MjU4MDA3MiwiZXhwIjoxNjQyNTgwMTkyfQ.HmIDcuSW67A59x7bnumjGp0Wdcz-FmoDrnHF1YGui6wVPfulLn4Izonay5LQnySgph1dbyC1E0LtifS-BJo8VA",
    "expiredTime":1642580192430
    },
    "extra":null,
    "transactionId":"6c2c50a3049ce67e",
    "pricingStrategy":"FREE"
}

Example of PARAMETER_ERROR Response:

{
    "code":"PARAMETER_ERROR",
    "message":"Parameter should not be empty",
    "data":null,
    "extra":null,
    "transactionId":"040e769e38f87e3e",
    "pricingStrategy":"FREE"
 }

{
    "code":"PARAMETER_ERROR",
    "message":"Timestamp error",
    "data":null,
    "extra":null,
    "transactionId":"a9c2a6c199ad5db5",
    "pricingStrategy":"FREE"
}

{
    "code":"PARAMETER_ERROR",
    "message":"Signature error",
    "data":null,
    "extra":null,
    "transactionId":"00b05cb9cf6f0fed",
    "pricingStrategy":"FREE"
}

Example of ACCOUNT_DISABLED Response:

{
    "code":"ACCOUNT_DISABLED",
    "message":"Account Disabled",
    "data":null,
    "extra":null,
    "transactionId":"5e00fded1272490e",
    "pricingStrategy":"FREE"
}

Example of CLIENT_ERROR Response:

{
    "code":"CLIENT_ERROR",
    "message":"HTTP 400 - Bad Request",
    "data":null,
    "extra":null,
    "transactionId":"bd5d5653c45d4c6e",
    "pricingStrategy":"FREE"
 }

Response Description:

Parameter	Description
`code`	Response Status Code
`message`	Message returned from server
`data`	`token` AccessToken
	`expiredTime` Expiration timestamp
`extra`	Extra response info such as exception message
`transactionId`	the request id, the max length is 64
`pricingStrategy`	whether the request will be charged, enum type: `FREE`, `PAY`

Response Code

Status Code	Message
`SUCCESS`	`free` OK
`PARAMETER_ERROR`	`free` Parameter should not be empty
	`free` Timestamp error
	`free` Signature error
`ACCOUNT_DISABLED`	`free` Account Disabled
`CLIENT_ERROR`	`free` HTTP 400 - Bad Request

Glossary

Welcome to the Glossary!

Please read the following to understand how ADVANCE API system, for a smooth integration. We will explain all the basics you need to know about our API.

Status Code

Our API responses will contain a Status Code indicating the result of the API call, whether it was successful, or an error occurred during the process
Each API will also have its own unique Status Codes that can only be found in the responses of the API
Your API usage will be charged based on the response Status Code, each Status Code listed in our API document will have either a free or pay tag with it
free means you will not be charged and paymeans that you will be charged
pay means you will be charged if the API response contains the said status code
Below are the commonly used Status Codes, these status codes could appear in all our API responses, so please remember to add a handler for these Status Codes

Notes:

Please use ‘Status Code’ in your strategy instead of ‘Message’, as 'Message’ is a detailed explanation for developer’s reference and may update without ADVANCE Notice.

Status Code	Message
`SUCCESS`	`pay` OK
`ERROR`	`free` Server error
`EMPTY_PARAMETER_ERROR`	`free` Parameter should not be empty
`INSUFFICIENT_BALANCE`	`free` Insufficient balance, please top up or contact your sales manager for help
`SERVICE_BUSY`	`free` Messages may look like: Rate limit is exceeded, please retry after the suggested time in HTTP Header. Retry-After :10s p.s. Please also note that this code may migrate to HTTP 429 Too Many Requests in the future. Quota exceeded: You have exceeded the daily quota for free queries, please contact out tech support for help
`IAM_FAILED`	`free` Access denied. Messages may look like: You are not authorized by the Identity and Access Management system Access Key not found Token not found or expired Access Key not found or expired Account not authorized for this country Account not authorized for this domain Account is expired. Please contact your sales manager for help Account is disabled. Please contact your sales manager for help Access denied: Token not found or expired
`PARAMETER_ERROR`	`free` The message is detailed error description, may includes: Parameter should not be empty Invalid phone number, please check your phone number format etc. p.s. Mobile number format should be country code + phone number(without leading 0 or dash or space e.g. +xx12345678); fixed-line number should be country code + area code + number(without leading 0)
`OVER_QUERY_LIMIT`	`free` Messages may look like: Quota exceeded. you have exceeded free query quota, please contact your sales manager for help Quota exceeded: You have exceeded free query quota for test account, please contact your sales manager for help
`CLIENT_ERROR`	`free` HTTP client error. Messages may look like: HTTP 400 - Bad Request HTTP 404 - Not Found HTTP 405 - Method Not Allowed etc. If you get this error, please check the API document or contact our tech support for help.
`RETRY_LATER`	`free` Query failed, please retry after the suggested time in HTTP Header. Retry-After :10s

Notes:

If the Status Code is SUCCESS, it may not be charged. Please check the code returned by each interface

Request URL & Parameters

Request URL can be found at each API document along with the request method (POST or GET or other request method) and Content Type (application/json or other content type)
Some parameters will have optional tag on them, this means the parameter is not mandatory for the request and they can be empty, however adding them might produce more accurate result, for example : Company check, zip code is an optional parameter but adding zip code parameter will return all the companies around that said zip code instead of all around Indonesia.
If a parameter does not have an optional tag, it means the parameter is mandatory and making request without them will return EMPTY_PARAMETER_ERROR response
Every parameter has a data type such as string, integer and file, please double check the parameter data type before making any request
Here’s an example of parameter explanation that can be found on each API document

Parameter	Description
requestString	`string` String value for API request
requestFile	`file` Request file for API request
requestInteger	`optional` `integer` Number value for API request

Response

ADVANCE API responds in JSON format
ADVANCE API response consists of 4 fields:
- code the Status Code;
- message detailed explanation of the Status Code;
- extra an exception message (should be empty most of the time);
- data the response content from ADVANCE;
Each service has its own data format, outlined in the API document
If the response format is very complicated (multiple different JSON object, nested JSON object), please refer to the Breakdown section of the Response Explanation
transactionId: It is strongly recommended to save the transactionId.
The following is an example of Response Explanation found in each API document:

Parameter	Description
code	API Status Code
message	Status Code Explanation
data	`field1`: explanation of the first information that will be returned from ADVANCE
	`field2`: explanation of the second information that will be returned from ADVANCE
extra	Extra response info (Exception Message)

Image Quality Requirements

The services check and extract the necessary information from the uploaded images, hence please ensure the uploaded images satisfy the following criteria:
- Is in one of the following image formats: PNG / JPG / JPEG
- Below 2 MB file size
- Minimum resolution of 256 x 256
- Maximum resolution of 4096 x 4096
For OCR services please also ensure that the uploaded images satisfy the following criteria:
- ID Card’s ratio in the uploaded photo is not so small that the words in the ID Card are unreadable
- ID Card’s orientation is in Vertical or Horizontal position and NOT heavily tilted (around 45 degree)
- Nothing is covering up the words in the ID Card (ex: Light Spot, Dirt, Ink, Shadow, etc)
- Have a clean background (No words or other picture in the background)