TrustDecision
API Reference
中文

OCR API V2.0

Base URL

API

URLRequest MethodsContent TypeOutput FormatCharacter Set
api-base-url?partner_code=xxx&partner_key=xxxPOSTapplication/jsonJSONUTF-8

Authentication

ParameterTypeDescriptionRequired/OptionalNotes
partner_codeStringPartner CodeRequiredAssigned by TD
partner_keyStringPartner KeyRequiredAssigned by TD

Request

ParameterTypeDescriptionRequired/OptionalNotes
imageStringID card imageRequiredBase64 encoded image character stream of JPG, JPEG, PNG, the image cannot exceed 2M
countryStringCountryRequiredCountry, required. Two-digit country code (uppercase). Compliant with ISO 3166 standard, such as Mexico: MX
scenarioStringSceneRequiredEnumeration value:Ocr
optionsStringAdditional feature outputOptionalEnumeration value:
1. images: to output document image, portraits, signature etc.
2. image_quality: to output image quality related parameters
3. document_forgery: Returns forgery detection parameters
Support multiple selections, separated by commas, for example: images, image_quality, document_forgery

OCR Image Specifications and Requirements

Requirement CategorySpecific Guidelines and Requirements
Document Placement- Ensure the document is centered in the image, with all four edges clearly visible and not obscured or cropped.
- Maintain the original aspect ratio of the document to avoid distortion.
- Avoid using non-authentic online samples (such as images found on the internet), blurry photographs, incomplete document edges, or severely distorted images.
Image Quality- Capture the image in an environment with adequate and even lighting, avoiding direct strong light or shadows.
- Use a single, preferably light-colored background without complex patterns or textures.
- Ensure the test image is clear, without blurriness or overexposure issues.
Image Specifications- The file size of the image should ideally be between 100KB and 500KB to ensure fast upload speeds and efficient processing, while avoiding excessive compression that could degrade recognition quality.

Examples of Acceptable Pictures:

Examples of Non-acceptable Pictures:

Response

ParameterTypeDescriptionNotes
codeIntegerAPI status code
messageStringStatus informationWhen the API is in an abnormal state, the specific abnormal reasons are returned
sequence_idStringUnique response codeTo track the unique identification of each request
resultStringVerification resultEnumeration value:
1. success: if document type can be recognized, document is not expired, MRZ (if applicable) is valid and the format of text fields is valid, it will return success
2. error: if any one of the above document type, expiry, MRZ and text fields check fails, it will return error.
In this case, it only represents verification failure, not an OCR parsing failure. OCR parsing information may still be returned in the card_info field.
3. not performed: checks are not performed
status_infoObjectVerification detailsDetails of above result including verification details of document type, expiry, MRZ and text fields.
Please refer to the data object of StatusInfo
document_type_infoObjectDocument type informationDefault parameter.
Please refer to the data object of DocumentTypeInfo
card_infoObjectID card informationOCR results for the identification document are returned in this section; the presence of data indicates a successful OCR outcome.
Despite a 'result' field returning 'error', the OCR interpretation information may still be present in this field.
Please refer to the data object of Cardinfo
image_infoObjectImage informationWill be returned when related input parameter is selected.
Even if the return value of the result field is 'error', this field may still return OCR parsing information.
Please refer to the data object of ImageInfo
image_quality_infoObjectImage quality informationWill be returned when related input parameter is selected.
Please refer to the data object of ImageQualityInfo
document_forgery_infoObjectDocument forgery detectionWill be returned when related input parameter is selected.
Please refer to the data object of DocumentForgeryInfo

Data Objects

  • StatusInfo
    ParameterTypeDescriptionNotes
    doc_typeIntegerCheck whether the document type can be correctly identifiedPlease refer to the CheckResult data dictionary
    expiryIntegerCheck whether the document has expiredPlease refer to the CheckResult data dictionary
    mrzIntegerCheck whether the MRZ (Machine Readable Zone) is correctly recognizedPlease refer to the CheckResult data dictionary
    textIntegerCheck whether the text format of the fields on the document meets the requirementsPlease refer to the CheckResult data dictionary
    {
        "doc_type":1,
        "expiry":0,
        "mrz":1,
        "text":1
}
  • DocumentTypeInfo
    ParameterTypeDescriptionNotes
    document_nameStringDetailed document name
    document_descriptionStringDocument typeIdentity Card, Passport, Driving License etc
    {
        "document_name":"Philippines - ePassport (2016)",
        "document_description":"Passport"
}
  • CardInfo
    ParameterTypeDescriptionNotes
    field_listArray
    /Object    		List of text field name
    field_list.field_nameStringText field name
    fieldList.lcidIntegerType LCIDPlease refer to LCID data dictionary
    field_list.validity_statusIntegerEffective state of text fieldsCheck if the format of the text fields are valid.
    Please refer to CheckResult data dictionary
    field_list.value_listArrayText field value list
    field_list.value_list.original_valueStringText field original valueThe original value appeared on the document
    field_list.value_list.valueStringTest field valueThe parsed value based on original value field. Eg. for date type information, the format will be YYYY-MM-DD
    {
    "field_list":[
        {
            "field_name":"Date of Expiry",
            "lcid":0,
            "validity_status": 1,
            "value_list":[
                {
                    "original_value":"23/08/2024",
                    "value":"2024-08-23"
                }
            ]
        },
        {
            "field_name":"Date of Birth",
            "lcid":0,
            "validity_status": 1,
            "value_list":[
                {
                    "original_value":"01/01/1979",
                    "value":"1979-01-01"
                }
            ]
        }
    ]
}
  • ImageInfo
    ParameterTypeDescriptionNotes
    field_listObjectList of graphics field name
    field_list.field_nameStringGraphic field name
    field_list.value_listObjectList of graphics field values
    field_list.value_list.valueStringGraphical field valueImage, base64 format.
    {
    "field_list":[
        {
            "field_name":"Portrait",
            "value_list":[
                {
                    "value":"/4AAQSkZJRgABAQEBHwEfAADxxxxxx"
                }
            ]
        },
        {
            "field_name":"Signature",
            "value_list":[
                {
                    "value":"/9j/4AAQSkZJRgABAQE***” "
                }
            ]
        }
    ]
}
  • ImageQualityInfo
    ParameterTypeDescriptionNotes
    resultIntegerOverall result
    listObjectList of inspection results
    list.resultIntegerSingle inspection resultsPlease refer to the CheckResult data dictionary
    list.feature_typeIntegerInspection areaReserved parameter, default to be 0
    list.typeIntegerSingle inspection typeThe type of test results.
    Please refer to ImagequalityCheckType data dictionary
  • {
  "list": [
    {
      "feature_type":0,
      "result": 1,
      "type": 1
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 0
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 7
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 5
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 4
    },
    {
      "feature_type":0,
      "result": 1,
      "type": 2
    }
  ],
  "result": 1
}
    DocumentForgeryInfo
    ParameterTypeDescriptionNotes
    resultStringOverall result of forgery detectionEnumeration:

    1. pass: Passed, document is not forged
    2. fail: Failed, document is forged
    detailObjectList of forgery detection detailsIf the result is "pass", this field is not returned; if the result is "fail", this field will list specific reasons, such as "black_white_print" (black and white print) and "screen_capture" (screen capture)
  • {
    "result":"fail",
    "detail":[
     "black_white_print"
     ]
}

Data Dictionary

  • CheckResult

    CodeMessageDescription
    0ERRORCheck was performed and result is NEGATIVE
    1OKCheck was performed and result is POSITIVE
    2WAS_NOT_DONECheck was NOT PERFORMED

  • ImageQualityCheckType

    CodeMessageDescription
    0ImageGlaresSignals glare presence on the image
    1ImageFocusSignals whether image is in focus
    2ImageResolutionSignals if image resolution is below threshold
    3ImageColornessSignals if image is colorless
    4PerspectiveSignals if document in the image has prespective distortion above threshold
    5BoundsSignals if document is not fully present in the image
    6ScreenCaptureSignals if an image is captured from screen
    7PortraitSignals if the portrait is present clearly

  • LCID

    CodeMessageDescription
    0LATINLatin
    1078AFRIKAANSAfrikaans
    1052ALBANIANAlbanian
    5121ARABIC_ALGERIAArabic (Algeria)
    15361ARABIC_BAHRAINArabic (Bahrain)
    3073ARABIC_EGYPTArabic (Egypt)
    2049ARABIC_IRAQArabic (Iraq)
    11265ARABIC_JORDANArabic (Jordan)
    13313ARABIC_KUWAITArabic (Kuwait)
    12289ARABIC_LEBANONArabic (Lebanon)
    4097ARABIC_LIBYAArabic (Libya)
    6145ARABIC_MOROCCOArabic (Morocco)
    8193ARABIC_OMANArabic (Oman)
    16385ARABIC_QATARArabic (Qatar)
    1025ARABIC_SAUDI_ARABIAArabic (Saudi Arabia)
    10241ARABIC_SYRIAArabic (Syria)
    7169ARABIC_TUNISIAArabic (Tunisia)
    14337ARABIC_UAEArabic (U.A.E.)
    9217ARABIC_YEMENArabic (Yemen)
    1067ARABIC_ARMENIANArmenian
    2092AZERI_CYRILICAzeri (Cyrillic)
    1068AZERI_LATINAzeri (Latin)
    1069BASQUEBasque
    1059BELARUSIANBelarusian
    1026BULGARIANBulgarian
    1027CATALANCatalan
    3076CHINESE_HONGKONG_SARChinese (HongKong S.A.R.)
    5124CHINESE_MACAO_SARChinese (Macao S.A.R.)
    2052CHINESEChinese
    4100CHINESE_SINGAPOREChinese (Singapore)
    1028CHINESE_TAIWANChinese (Taiwan)
    1050CROATIANCroatian
    1029CZECHCzech
    1030DANISHDanish
    1125DIVEHIDivehi
    2067DUTCH_BELGIUMDutch (Belgium)
    1043DUTCH_NETHERLANDSDutch (Netherlands)
    3081ENGLISH_AUSTRALIAEnglish (Australia)
    10249ENGLISH_BELIZEEnglish (Belize)
    4105ENGLISH_CANADAEnglish (Canada)
    9225ENGLISH_CARRIBEANEnglish (Caribbean)
    6153ENGLISH_IRELANDEnglish (Ireland)
    8201ENGLISH_JAMAICAEnglish (Jamaica)
    5129ENGLISH_NEW_ZEALANDEnglish (New Zealand)
    13321ENGLISH_PHILIPPINESEnglish (Philippines)
    7177ENGLISH_SOUTH_AFRICAEnglish (South Africa)
    11273ENGLISH_TRINIDADEnglish (Trinidad)
    2057ENGLISH_UKEnglish (United Kingdom)
    1033ENGLISH_USEnglish (United States)
    12297ENGLISH_ZIMBABWEEnglish (Zimbabwe)
    1061ESTONIANEstonian
    1080FAEROESEFaeroese
    1065FARSIFarsi
    1035FINNISHFinnish
    2060FRENCH_BELGIUMFrench (Belgium)
    3084FRENCH_CANADAFrench (Canada)
    1036FRENCH_FRANCEFrench (France)
    5132FRENCH_LUXEMBOURGFrench (Luxembourg)
    6156FRENCH_MONACOFrench (Monaco)
    4108FRENCH_SWITZERLANDFrench (Switzerland)
    1071FYRO_MACEDONIANFYRO Macedonian
    1110GALICIANGalician
    1079GEORGIANGeorgian
    3079GERMAN_AUSTRIAGerman (Austria)
    1031GERMAN_GERMANYGerman (Germany)
    5127GERMAN_LIECHTENSTEINGerman (Liechtenstein)
    4103GERMAN_LUXEMBOURGGerman (Luxembourg)
    2055GERMAN_SWITZERLANDGerman (Switzerland)
    1032GREEKGreek
    1095GUJARATIGujarati
    1037HEBREWHebrew
    1081HINDI_INDIAHindi (India)
    1038HUNGARIANHungarian
    1039ICELANDICIcelandic
    1057INDONESIANIndonesian
    1040ITALIAN_ITALYItalian (Italy)
    2064ITALIAN_SWITZERLANDItalian (Switzerland)
    1041JAPANESEJapanese
    1099KANNADAKannada
    1087KAZAKHKazakh
    1111KONKANIKonkani
    1042KOREANKorean
    1088KYRGYZ_CYRILICKKyrgyz (Cyrillic)
    1062LATVIANLatvian
    1063LITHUANIANLithuanian
    1086MALAY_MALAYSIAMalay (Malaysia)
    2110MALAY_BRUNEI_DARUSSALAMMalay (Brunei Darussalam)
    1102MARATHIMarathi
    1104MONGOLIAN_CYRILICMongolian (Cyrillic)
    1044NORWEGIAN_BOKMALNorwegian (Bokmal)
    2068NORWEGIAN_NYORSKNorwegian (Nynorsk)
    1045POLISHPolish
    1046PORTUGUESE_BRAZILPortuguese (Brazil)
    2070PORTUGUESE_PORTUGALPortuguese (Portugal)
    1094PUNJABIPunjabi
    1047RHAETO_ROMANICRhaeto-Romanic
    1048ROMANIANRomanian
    1049RUSSIANRussian
    1103SANSKRITSanskrit
    3098SERBIAN_CYRILICSerbian (Cyrillic)
    2074SERBIAN_LATINSerbian (Latin)
    1051SLOVAKSlovak
    1060SLOVENIANSlovenian
    11274SPANISH_ARGENTINASpanish (Argentina)
    16394SPANISH_BOLIVIASpanish (Bolivia)
    13322SPANISH_CHILESpanish (Chile)
    9226SPANICH_COLOMBIASpanish (Colombia)
    5130SPANISH_COSTA_RICASpanish (Costa Rica)
    7178SPANISH_DOMINICAN_REPUBLICSpanish (Dominican Republic)
    12298SPANISH_ECUADORSpanish (Ecuador)
    17418SPANISH_EL_SALVADORSpanish (El Salvador)
    4106SPANISH_GUATEMALASpanish (Guatemala)
    18442SPANISH_HONDURASSpanish (Honduras)
    2058SPANISH_MEXICOSpanish (Mexico)
    19466SPANISH_NICARAGUASpanish (Nicaragua)
    6154SPANISH_PANAMASpanish (Panama)
    15370SPANISH_PARAGUAYSpanish (Paraguay)
    10250SPANISH_PERUSpanish (Peru)
    20490SPANISH_PUERTO_RICOSpanish (Puerto Rico)
    1034SPANISH_TRADITIONAL_SORTSpanish (Traditional Sort)
    3082SPANISH_INTERNATIONAL_SORTSpanish (International Sort)
    14346SPANISH_URUGUAYSpanish (Uruguay)
    8202SPANISH_VENEZUELASpanish (Venezuela)
    1089SWAHILISwahili
    1053SWEDISHSwedish
    2077SWEDISH_FINLANDSwedish (Finland)
    1114SYRIACSyriac
    1097TAMILTamil
    1092TATARTatar
    1098TELUGUTelugu
    1054THAI_THAILANDThai (Thailand)
    1055TURKISHTurkish
    1064TAJIK_CYRILLICTajik (Cyrillic)
    1090TURKMENTurkmen
    1058UKRAINIANUkrainian
    1056URDUUrdu
    2115UZBEK_CYRILICUzbek (Cyrillic)
    1091UZBEK_LATINUzbek (Latin)
    1066VIETNAMESEVietnamese
    50001CTC_SIMPLIFIEDCTC Simplified
    50002CTC_TRADITIONALCTC Traditional

Status Code

Code MessageDescription
200SuccessCall Successfully
301Service not purchasedNo purchase of the servive
302Traffic blockedTraffic blocked
303Traffic insufficientTraffic insufficient
304Service expiredService expired
305Daily maximum volume reachedDaily maximum volume reached
11350Internal errorInternal error
11301{parameter} empty{parameter} empty
11304The country partner located is not openThe country partner located is not open
11340{parameter} error{parameter} error

Parameter Examples：

  • Input parameter

    {
  "image": "/9j/4AAQSkZJRgABAQAAeAB4AAD/********XLiqqauzsw1J3sf/2Q==",
  "country": "GB",
  "scenario": "Ocr",
  "options": "images,image_quality,document_forgery"
}

  • Success

{
    "result":"success",
    "code":200,
    "sequence_id":"2a7515e2bc094********20cf1ca0f72",
    "message":"success",
    "status_info":{
        "doc_type":1,
        "expiry":1,
        "mrz":1,
        "text":1
    },
    "document_type_info":{
        "document_name":"Philippines - ePassport (2016)",
        "document_description":"Passport"
    },    
    "card_info":{
        "field_list":[
            {
                "field_name":"Date of Expiry",
                "validity_status":1,
                "value_list":[
                    {
                        "original_value":"23/08/2024",
                        "value":"2024-08-23"
                    }
                ]
            },
            {
                "field_name":"Date of Birth",
                "validity_status":1,
                "value_list":[
                    {
                        "original_value":"01/01/1979",
                        "value":"1979-01-01"
                    }
                ]
            }
        ]
    },
    "image_info":{
        "field_list":[
            {
                "field_name":"Portrait",
                "value_list":[
                    {
                        "value":"/4AAQSkZJRgABAQEBHwEfAADxxxxxx"
                    }
                ]
            },
            {
                "field_name":"Signature",
                "value_list":[
                    {
                        "value":"/9j/4AAQSkZJRgABAQE***” "
                    }
                ]
            }
        ]
    },
    "image_quality_info":{
        "list":[
            {
                "feature_type":0,
                "result":1,
                "type":1
            },
            {
                "feature_type":2,
                "result":1,
                "type":0
            },
            {
                "feature_type":3,
                "result":1,
                "type":7
            },
            {
                "feature_type":4,
                "result":1,
                "type":5
            },
            {
                "feature_type":5,
                "result":1,
                "type":4
            },
            {
                "feature_type":6,
                "result":1,
                "type":2
            }
        ],
        "result":1
    },
  "document_forgery_info":{
    "result":"fail",
    "detail":[
     "black_white_print"
     ]
  }
}
  • Failed
{
    "code": 302,
    "sequence_id": "69b57131b6fb********61ccba118b60",
    "message": "Traffic blocked"
}