NAV Navbar
Logo

KK OCR

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

Code Sample

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

Request Url

https://api.advance.ai/openapi/face-identity/v1/ocr-kk-check
POST (form-data)

Notes:

Request Header Parameters:

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

Request Parameters:

Parameter Description
ocrImage file An image（PNG/JPG/JPEG/TIF format）

Note: Please check the OCR image quality requirements in Glossary to ensure OCR could work properly

Example of Success Response:

{
    "code":"SUCCESS",
    "message":"OK",
    "data":{
            "address":"KP. *******",
            "familyHead":"*******",
            "subDistrict":"*******",
            "postcode":"*******",
            "village":"*******",
            "rtrw":"003/006",
            "province":"JAWA BARAT",
            "district":"BEKASI",
            "personList":[
               {
                     "person":"person1",
                     "idNumber":"3**************",
                     "name":"*******",
                     "birthPlace":"*******",
                     "occupation":"******* *******",
                     "birthDate":"15-06-1960",
                     "religion":"ISLAM",
                     "marriageDate":"",
                     "bloodType":"",
                     "statusInFamily":"******* *******",
                     "gender":"LAKI-LAKI",
                     "education":"TAMAT SD/*******",
                     "nationality":"WNI",
                     "maritalStatus":"KAWIN",
                     "passport":"",
                     "nameOfFather":"ENTO",
                     "nameOfMother":"ENDEH",
                     "kitap":""
               }
            ],
            "kk":"**************"
    },
    "extra":null,
    "pricingStrategy":"PAY"
}

Example No Result Response:

   {
        "message": "OCR check failed, unable to find any kk field in the uploaded picture",
        "data": null,
        "extra": null,
        "code": "OCR_NO_RESULT",
        "transactionId": "196eb0c777789e58",
        "pricingStrategy": "PAY"
    }

Example of Empty Parameter Error Response:


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

    {
      "code": "PARAMETER_ERROR",
      "message": "Invalid image format, image format should be one of jpeg/jpg/png/tif, and request content type should be image/jpeg,image/png or image/tif",
      "data": null,
      "extra": null,
      "transactionId": "1777796eb0c89e58",
      "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": "1960c77eb7789e58",
      "pricingStrategy": "FREE"
    }

Response Description:

Parameter Description
code KK 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 address : Address of the family
familyHead : Name of the head of family
subDistrict : Sub-district of the family
postcode : Postcode of the family
village : Village of the family
rtrw : RT/RW of the family
province : Province of the family
district : District of the family
personList : please click here for the breakdown of this JSON array object
kk : KK number of the family
extra Extra response info (Exception Message)

Response Object Breakdown:

personList:

Field Name Description
person string Preson N
idNumber string ID Number (NIK) of the Person
name string Name of the person
birthPlace string Birthplace of the person
occupation string Occupation of the person
birthDate string Birthday of the person
religion string Religion of the person
marriageDate string Date of Marriage of the person
bloodType string Blood type of the person
statusInFamily string Status in Family of the person
gender string Gender of the person
education string Education of the person
nationality string Nationality of the person
maritalStatus string Marital Status of the person
passport string Passport number of the person
nameOfFather string Father’s Name of the person
nameOfMother string Mother’s Name of the person
kitap string KITAP number of the person

Response Code

Status Code Message
PARAMETER_ERROR free parameter error details refer to the samples on the right
OCR_NO_RESULT pay OCR check failed, unable to find any kk field in the uploaded picture

Note: Don’t Forget to add handler for these Status Codes in 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:

Code Sample

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

Request Url

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

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

Notes:

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:

Request URL & Parameters

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

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