OCR Document Last updated: 2022-11-01

OCR (Optical Character Recognition) Document

This is API specification for OCR (Optical Character Recognition) Document as a part of eKYC service provided by FinOS Technology VN.
Version : v1.0.0

Prerequisite

Steps

Step 1 : Register an account at
Step 2 : Search API want to use and do the Subscribe
Step 3 : Get [API Key] and add to header of request

Variables

Name	Description
[API Key]	Authorization key, value get from subscription
[Host]	Based on environment :
	Trial : https://api-gw.sandbox.finos.asia/
	Production : https://apigw.finos.asia/

National ID card extraction

1. Request

Method	URL
POST	[Host]/ekyc/ocr/v2/nationalID

Header

Header	Value	Required	Note
X-FinOS-Api-Key	[API Key]	Yes
transactionId	Unique Id	No

Body

Params	Type	Required	Note
image	File	Yes	Image file
enableAddressSplit	String	No	Split field permanentAddress into separate province, ward, district. Possible value : yes / no
qualityCheck	String	No	Allow do quality check. Possible value : yes / no

2. CURL


curl --location --request POST '[Host]/ekyc/ocr/v2/nationalID' \
	--header 'Content-Type: multipart/form-data;' \
	--header 'Accept-Encoding: gzip, deflate, br' \
	--header 'X-FinOS-Api-Key: [API Key]' \
	--header 'transactionId: test-postman' \
	--form 'image="/cccd_chip.png"' \
	--form 'enableAddressSplit="yes"' \
	--form 'fraudCheck="yes"' \
	--form 'faceCheck="yes"' \
	--form 'forgeryCheck="yes"' \
	--form 'qualityCheck="yes"'

3. HTTP Status

Status Code	Error Message	Error Description
400	Invalid image file uploaded	This error is returned when ‘image’ is not sent or more than 2 images in the API call
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
413	The request is larger than the server is willing or able to process	Uploaded image too large
422	National ID not detected	Service could not find National ID in input image
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request

4. Object “SUMMARY” in response

This object is help to consolidating all the checks during the processing.

Possible value : “Manual Review” & “pass”

Error Message

Code	Message	Check Type
001	Không nhận diện được CMND/ CCCD
046	Không nhận diện được ảnh chân dung trên CMND/CCCD	Quality Check
044	Vui lòng chỉ chụp CMND/ CCCD gốc	Quality Check
045	CMND/CCCD chụp từ thiết bị khác	Quality Check
047	CMND/CCCD đã bị cắt góc	Quality Check
048	CMND/CCCD bị mờ	Quality Check
049	CMND/CCCD bị chói sáng	Quality Check
061	CMND/CCCD không hợp lệ	Rule Check - Date Of Expiry Validation
063	ID Number Gender Code Invalid	Rule Check - Year Of Birth & Gender Code Validation
064	CMND/CCCD không hợp lệ	Rule Check - ID Number Validation (Length of ID number is either 9 or 12 digits)

5. Response

200 : Success

								
{
	"status": "success",
	"statusCode": "200",
	"result": {
		"details": [
			{
				"fieldsExtracted": {
					"idNumber": {
						"value": "030187003568",
						"to-be-reviewed": "no"
					},
					"name": {
						"value": "PHẠM THỊ THU THỦY",
						"to-be-reviewed": "no"
					},
					"dob": {
						"value": "08-08-1987",
						"to-be-reviewed": "no"
					},
					"homeTown": {
						"value": "Xã Thanh Lang, Huyện Thanh Hà, Tỉnh Hải Dương",
						"to-be-reviewed": "no"
					},
					"permanentAddress": {
						"value": "P509-K2 Nghĩa Tân, Cầu Giấy, Hà Nội",
						"province": "Hà Nội",
						"ward": "P509-K2 Nghĩa Tân",
						"district": "Cầu Giấy",
						"street": "",
						"to-be-reviewed": "no"
					},
					"gender": {
						"value": "Nữ",
						"to-be-reviewed": "no"
					},
					"doe": {
						"value": "08-08-2027",
						"to-be-reviewed": "no"
					},
					"nationality": {
						"value": "Việt Nam",
						"to-be-reviewed": "no"
					}
				},
				"qualityChecks": {
					"faceNotDetected": {
						"value": "no",
						"to-be-reviewed": "no"
					},
					"blur": {
						"value": "no",
						"to-be-reviewed": "no"
					},
					"glare": {
						"value": "no",
						"to-be-reviewed": "no"
					},
					"partialID": {
						"value": "no",
						"to-be-reviewed": "no"
					},
					"blackAndWhite": {
						"value": "no",
						"to-be-reviewed": "no"
					},
					"capturedFromScreen": {
						"value": "no",
						"to-be-reviewed": "no"
					}
				},
				"ruleChecks": {
					"idDOBGenderCodeInvalid": {
						"value": "no",
						"to-be-reviewed": "no"
					},
					"idNumberLengthMismatch": {
						"value": "no",
						"to-be-reviewed": "no"
					}
				},
				"tamperChecks": {},
				"type": "cccd_chip_front"
			}
		],
		"summary": {
			"action": "pass",
			"details": []
		}
	},
	"requestId": "5ec86801-ce39-429c-8868-01ce39529c26",
	"transactionId": "FinOS_An_Test_Transaction"
}

400 : Input has error

								
{
	"status": "failure",
	"statusCode": "400",
	"error": "Invalid image file uploaded",
	"requestId": "9d513529-6582-4ed3-8a5f-45a6383cc471",
	"transactionId": "FinOS_An_Test_Transaction"
}

401 : Unauthorization

								
{
	"message": "Unauthorized",
	"http_status_code": 401
}

422 : National ID not detected

								
{
	"status": "failure",
	"statusCode": "422",
	"result": {
		"summary": {
			"action": "Manual Review",
			"details": [
				{
					"code": "001",
					"message": "Không nhận diện được CMND/ CCCD"
				}
			]
		}
	},
	"error": "Vietnam National ID Not Detected",
	"requestId": "d88de077-9f5e-4b10-8de0-779f5eeb103a",
	"transactionId": "FinOS_Automation_Test_Transaction"
}

500 : Server error

								
{
	"status": "failure",
	"statusCode": "500",
	"error": "Internal Server Error"
}

6. Data Extracted

VietNam ID Card Type	Type Code	Fields
Old Nation ID Front Side	cmnd_old_front	idNumber, name, dob, province, homeTown, permanentAddress
Old Nation ID Back Side	cmnd_old_back	doi, placeOfIssue, doe, ethnicity
New National ID Front Side	cmnd_new_front	idNumber, name, gender, dob, permanentAddress, doi, doe, province, homeTown, ethnicity
Citizen ID Front Side	cccd_front	idNumber, name, gender, dob, permanentAddress, doi, doe, province, homeTown, nationality
New National ID/Citizen ID Back Side	cmnd_new_cccd_back	doi, placeOfIssue
Chip Citizen ID Front Side	cccd_chip_front	idNumber, name, gender, dob, permanentAddress, doe, province, homeTown, nationality
Chip Citizen ID Back Side	cccd_chip_back	doi, placeOfIssue

7. Document Checks

Quality Check

Name	Description	ID Card Type Supported
Glare Detection	Detect uploaded image are blured	cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front
Blur Detection	Detect uploaded image are glare due to flash light	cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front
Face Check	Detect user photo on the ID card is visible	cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front
Coner Cut Check	Check ID card is cut	cmnd_old_front, cmnd_new_front, cccd_front
Black & White Detection	Detect ID Card is a black & white photocopy	cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front
Captured From Screen Detection	Detect ID Card is captured from another screen	cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front
Partial ID Card Detection	Detect any edge of ID Card is cut off	cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front

Rule Check

Name	Description	ID Card Type Supported
Year Of Birth & Gender Code Validation	Check Year Of Birth & Gender matches with National ID number	cmnd_new_front, cccd_front, cccd_chip_front
National ID number Length Check	Check length of National ID number is correct	cmnd_old_front, cmnd_new_front, cccd_front, cccd_chip_front
Date Of Expiry Validation	Check the date of issued is pass the date of expiry

Vietnam Driver License Extraction

1. Request

Method	URL
POST	[Host]/ekyc/ocr/v1/readDL

Header

Header	Value	Required	Note
X-FinOS-Api-Key	[API Key]	Yes
transactionId	Unique Id	No

Body

Params	Type	Required	Note
image	File	Yes	Image file

2. CURL

curl --location --request POST '[Host]/ekyc/ocr/v1/readDL' \
							 --header 'Content-Type: multipart/form-data;' \
							 --header 'Accept-Encoding: gzip, deflate, br' \
							 --header 'X-FinOS-Api-Key: [API Key]' \
							 --header 'transactionId: test-postman' \
							 --form '"/dl.jpeg"'

3. HTTP Status

Status Code	Error Message	Error Description
400	Invalid image file uploaded	This error is returned when ‘image’ is not sent or more than 2 images in the API call
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
413	The request is larger than the server is willing or able to process	Uploaded image too large
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request

4. Response

200 : Success

{
								"status": "success",
								"statusCode": "200",
								"result": [
									{
										"type": "dl_new_front",
										"details": {
											"name": {
												"value": "LÊ VĂN A",
												"conf": 0.89,
												"to-be-reviewed": "no"
											},
											"dob": {
												"value": "23/01/1957",
												"conf": 0.59,
												"to-be-reviewed": "yes"
											},
											"expiry": {
												"value": "11/04/2024",
												"conf": 0.75,
												"to-be-reviewed": "yes"
											},
											"address": {
												"value": "89 Bình Quới P.13, Q4, TP. Hồ Chi Minh",
												"conf": 0.75,
												"to-be-reviewed": "yes"
											},
											"nationality": {
												"value": "Việt Nam",
												"conf": 1,
												"to-be-reviewed": "no"
											}
										}
									}
								],
								"requestId": "1651714366996-e41f102a-c5ce-454b-866b-07d19e95319b"
							}

400 : Input has error

{
								"status": "failure",
								"statusCode": "400",
								"error": "API call requires one input image",
								"requestId": "1651715773797-0dcdcace-1292-4aa4-9fec-48528a64ff78",
								"transactionId": "xxxxxx"
							}

401 : Unauthorization

{
								"requestId": "",
								"status": "failure",
								"statusCode": "401",
								"error": "API Key is not valid or is expired / revoked."
							}

500 : Server error

{
								"status": "failure",
								"statusCode": "500",
								"error": "Internal Server Error"
							}

Vietnam Passport Extraction

1. Request

Method	URL
POST	[Host]/ekyc/ocr/v1/readVNPassport

Header

Header	Value	Required	Note
X-FinOS-Api-Key	[API Key]	Yes
transactionId	Unique Id	No

Body

Params	Type	Required	Note
image	File	Yes	Image file

2. CURL

curl --location --request POST '[Host]/ekyc/ocr/v1/readVNPassport' \
							--header 'Content-Type: multipart/form-data;' \
							--header 'Accept-Encoding: gzip, deflate, br' \
							--header 'X-FinOS-Api-Key: [API Key]' \
							--header 'transactionId: test-postman' \
							--form '"/passport.jpeg"'

3. HTTP Status

Status Code	Error Message	Error Description
400	Invalid image file uploaded	This error is returned when ‘image’ is not sent or more than 2 images in the API call
413	The request is larger than the server is willing or able to process	Uploaded image too large
422	Passport not detected	This error is returned when passport not detected in ‘image’
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request

4. Response

200 : Success

{
								"status": "success",
								"statusCode": "200",
								"result": [
									{
										"type": "vn_passport_front",
										"details": {
											"place_of_issue": {
												"value": "Cục Quản lý xuất nhập cảnh",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"passport_num": {
												"value": "BC2810463",
												"conf": 0.88,
												"to-be-reviewed": "no"
											},
											"type": {
												"value": "P",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"name": {
												"value": "PHẠM THỊ TUYẾT",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"dob": {
												"value": "01/07/1999",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"gender": {
												"value": "NỮ/F",
												"conf": 0.95,
												"to-be-reviewed": "no"
											},
											"doe": {
												"value": "30/03/2027",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"doi": {
												"value": "30/03/2017",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"country_code": {
												"value": "VNM",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"place_of_birth": {
												"value": "TỈNH NAM ĐỊNH",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"nationality": {
												"value": "VIETNAMESE",
												"conf": 1,
												"to-be-reviewed": "no"
											},
											"fraudCheck": {
												"isBlackWhite": {
													"value": "no",
													"conf": 0.99,
													"to-be-reviewed": "no"
												}
											},
											"id": {
												"value": "192257877",
												"conf": 1,
												"to-be-reviewed": "no"
											}
										}
									}
								],
								"requestId": "1651715211177-d9ee1a5e-6395-47bc-84ad-4d8cbee13719"
							}

400 : Input has error

{
								"status": "failure",
								"statusCode": "400",
								"error": "API call requires one input image",
								"requestId": "1651715773797-0dcdcace-1292-4aa4-9fec-48528a64ff78",
								"transactionId": "xxxxxx"
							}

422 : Passport not detected

{
								"status": "failure",
								"statusCode": "422",
								"error": "Passport not detected",
								"requestId": "02d79c9d-5893-474e-979c-9d5893b74e9b",
								"transactionId": "xxxxxx"
							}

401 : Unauthorization

{
								"requestId": "",
								"status": "failure",
								"statusCode": "401",
								"error": "API Key is not valid or is expired / revoked."
							}

500 : Server error

{
								"status": "failure",
								"statusCode": "500",
								"error": "Internal Server Error"
							}

Vietnam MRC (Motor Registration Certificate)

1. Request

Method	URL
POST	[Host]/ekyc/ocr/v1/readMRC

Header

Header	Value	Required	Note
X-FinOS-Api-Key	[API Key]	Yes
transactionId	Unique Id	No

Body

Params	Type	Required	Note
image1	File	Yes	Image file
image2	File	No	Image file

2. CURL

curl --location --request POST '[Host]/ekyc/ocr/v1/readMRC' \
							--header 'Content-Type: multipart/form-data;' \
							--header 'Accept-Encoding: gzip, deflate, br' \
							--header 'X-FinOS-Api-Key: [API Key]' \
							--header 'transactionId: test-postman' \
							--form 'image2=@"/MRC_new_back.jpeg"' \
							--form 'image1=@"/MRC_old_back.png"'

3. HTTP Status

Status Code	Error Message	Error Description
400	API call requires one input image	This error is returned when 'image1' is not sent in the API call
400	Invalid image file uploaded	This error is returned when has more than 2 images sent under param 'image1' or 'image2' in the API call
413	The request is larger than the server is willing or able to process	Uploaded image too large
422	MRC not detected	This error is returned when mrc not detected in ‘image’
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request

4. Response

200 : Success

{
								"status": "success",
								"statusCode": "200",
								"result": [
									{
										"type": "old_register_card_back",
										"details": {
											"name": {
												"value": "TÔ THỊ NGHĨA",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"address": {
												"value": "Triều Khúc Tân Triều Thanh Trì",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"brand": {
												"value": "FUTURE",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"kind": {
												"value": "NỮ",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"color": {
												"value": "Đỏ",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"engine-number": {
												"value": "0632416",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"chassis-number": {
												"value": "218638",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"number-plate": {
												"value": "12X7-1210",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"place-registration": {
												"value": "Hà Nội",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"first-registration-date": {
												"value": "10/03/2007",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"last-registration-date": {
												"value": "10/3/2007",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"place-of-issue": {
												"value": "",
												"conf": 1.0,
												"to-be-reviewed": "yes"
											}
										}
									},
									{
										"type": "new_register_card_back",
										"details": {
											"name": {
												"value": "HOÀNG VĂN CHIỀU",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"address": {
												"value": "Làng Áng, Lâu Thượng, Võ Nhai, TN",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"brand": {
												"value": "HONDA",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"kind": {
												"value": "",
												"conf": 1.0,
												"to-be-reviewed": "yes"
											},
											"color": {
												"value": "Xám Đen",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"engine-number": {
												"value": "7F94E1949990",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"chassis-number": {
												"value": "QWZIF782XM2107638",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"number-plate": {
												"value": "30D2-136.44",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"place-registration": {
												"value": "Võ Nhân",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"first-registration-date": {
												"value": "",
												"conf": 1.0,
												"to-be-reviewed": "yes"
											},
											"last-registration-date": {
												"value": "20/03/2021",
												"conf": 1.0,
												"to-be-reviewed": "no"
											},
											"place-of-issue": {
												"value": "",
												"conf": 1.0,
												"to-be-reviewed": "yes"
											}
										}
									}
								],
								"requestId": "1b4c0d85-46e1-459c-8c0d-8546e1459ced",
								"transactionId": "transactionId"
							}

400 : Input has error

{
								"status": "failure",
								"statusCode": "400",
								"error": "API call requires one input image",
								"requestId": "97a92569-67f0-40d2-87ff-cbb5b6901223",
								"transactionId": "transactionId"
							}

{
								"status": "failure",
								"statusCode": "400",
								"error": "Invalid image file uploaded",
								"requestId": "21567e88-959f-4d54-a4e4-a36ea4e4a2d3",
								"transactionId": "transactionId"
							}

422 : MRC not detected

{
								"status": "failure",
								"statusCode": "422",
								"error": "MRC Not Detected",
								"requestId": "8e4df369-7a19-428a-8df3-697a19228a03",
								"transactionId": "transactionId"
							}

401 : Unauthorization

{
								"requestId": "",
								"status": "failure",
								"statusCode": "401",
								"error": "API Key is not valid or is expired / revoked."
								
							}

500 : Server error

{
								"status": "failure",
								"statusCode": "500",
								"error": "Internal Server Error",
								"requestId": "02d727c9d-5893-474e-979c-9d76867b74e9b",
								"transactionId": "transactionId"
							}

Face Service

Prerequisite

Steps

Step 1 : Register an account at
Step 2 : Search API want to use and do the Subscribe
Step 3 : Get [API Key] and add to header of request

Variables

Name	Description
[API Key]	Authorization key, value get from subscription
[Host]	Based on environment :
	Trial : https://api-gw.sandbox.finos.asia/
	Production : https://apigw.finos.asia/

Face Comparison

1. Request

Method	URL
POST	[Host]/ekyc/face/v1/photo/verifyPair

Header

Header	Value	Required	Note
transactionId	Unique Id	No
X-FinOS-Api-Key	[API Key]	Yes
threshold	1 --> 99	No	Allow dynamic setting threshold for comparison result

Body

Params	Type	Required	Note
image1	File	Yes	Image file
image2	File	Yes	Image file
type	String	Yes	Hard value : selfie

2. CURL

curl --location --request POST '[Host]/ekyc/face/v1/photo/verifyPair' \
						 --header 'Content-Type: multipart/form-data;' \
						 --header 'Accept-Encoding: gzip, deflate, br' \
						 --header 'X-FinOS-Api-Key: [API Key]' \
						 --header 'transactionId: test-postman' \
						 --header 'threshold: 85' \
						 --form 'image1=@"/image1.png"' \
						 --form 'image2=@"/image2.png"' \
						 --form 'type="selfie"'

3. HTTP Status

Status Code	Error Message	Error Description
400	Invalid image file uploaded	This error is returned when ‘image’ is not sent or more than 2 images in the API call
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
413	The request is larger than the server is willing or able to process	Uploaded image too large
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request

4. Response

200 : Success

{
							 "requestId": "1651717171648-d9f11786-ba4d-43e3-9a14-ad22570c175d",
							 "result": {
								 "conf": 99,
								 "match": "no",
								 "match_score": 3,
								 "match-score": 3,
								 "to-be-reviewed": "no"
							 },
							 "status": "success",
							 "statusCode": "200"
						 }

400 : Input has error

{
							 "requestId": "1651716921409-424055ac-8edd-4aa9-8820-2cc58431e05e",
							 "status": "failure",
							 "statusCode": "400",
							 "error": "Missing / Wrong combination of parameters. Valid Parameter combinations - (image1, image2, type) or (selfie, id) or (selfie, idFaceString)"
						 }

401 : Unauthorization

{
							 "requestId": "",
							 "status": "failure",
							 "statusCode": "401",
							 "error": "API Key is not valid or is expired / revoked."
						 }

500 : Server error

{
							 "status": "failure",
							 "statusCode": "500",
							 "error": "Internal Server Error"
						 }

Face Comparison (Id card & Selfie)

1. Request

Method	URL
POST	[Host]/ekyc/face/v1/photo/verifyPair

Header

Header	Value	Required	Note
transactionId	Unique Id	No
X-FinOS-Api-Key	[API Key]	Yes
threshold	1 --> 99	No	Allow dynamic setting threshold for comparison result

Body

Params	Type	Required	Note
selfie	File	Yes	Image file
id	File	Yes	Image file
fraudCheckLiveness	String	No	This feature only supports Passive Liveness Check request with params has the same transactionId in Passive Liveness Check request. Possible value : yes / no

2. CURL

curl --location --request POST '[Host]/ekyc/face/v1/photo/verifyPair' \
						 --header 'Content-Type: multipart/form-data;' \
						 --header 'Accept-Encoding: gzip, deflate, br' \
						 --header 'X-FinOS-Api-Key: [API Key]' \
						 --header 'transactionId: test-postman' \
						 --header 'threshold: 85' \
						 --form 'selfie=@"/selfie.png"' \
						 --form 'id=@"/id_card.png"'
						 --form 'fraudCheckLiveness="no"'

3. HTTP Status

Status Code	Error Message	Error Description
400	Invalid image file uploaded	This error is returned when ‘image’ is not sent or more than 2 images in the API call
400	Fraud check liveness failed	This error is returned when fraudCheckLiveness = yes & selfie in param doesn't match with selfie in liveness check
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
413	The request is larger than the server is willing or able to process	Uploaded image too large
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request

4. Response

200 : Success

{
							 "requestId": "1651719716436-80fd3269-418f-4c76-8de7-d5d187718ead",
							 "result": {
								 "conf": 88,
								 "match": "no",
								 "match_score": 12,
								 "match-score": 12,
								 "to-be-reviewed": "no"
							 },
							 "status": "success",
							 "statusCode": "200"
						 }

400 : Input has error

{
							 "requestId": "1651716921409-424055ac-8edd-4aa9-8820-2cc58431e05e",
							 "status": "failure",
							 "statusCode": "400",
							 "error": "Missing / Wrong combination of parameters. Valid Parameter combinations - (image1, image2, type) or (selfie, id) or (selfie, idFaceString)"
						 }

400 : Fraud check liveness failed

{
							"requestId": "bf07f13c-0a69-4a03-87f1-3c0a691a037e",
							"status": "failure",
							"statusCode": "400",
							"error": "Fraud check liveness failed"
						}

401 : Unauthorization

{
							 "requestId": "",
							 "status": "failure",
							 "statusCode": "401",
							 "error": "API Key is not valid or is expired / revoked."
						 }

500 : Server error

{
							 "status": "failure",
							 "statusCode": "500",
							 "error": "Internal Server Error"
						 }

Passive Liveness Check

1. Request

Method	URL
POST	[Host]/ekyc/face/v2/photo/liveness

Header

Header	Value	Required	Note
transactionId	Unique Id	No
X-FinOS-Api-Key	[API Key]	Yes

Body

Params	Type	Required	Note
image	File	Yes	Image file

2. CURL

curl --location --request POST '[Host]/ekyc/face/v2/photo/liveness' \
						 --header 'Content-Type: multipart/form-data;' \
						 --header 'Accept-Encoding: gzip, deflate, br' \
						 --header 'transactionId: asfdafsdfs' \
						 --header 'X-FinOS-Api-Key: [API Key]' \
						 --form 'image=@"/selfie.png"'

3. HTTP Status

Status Code	Error Message	Error Description
400	Invalid image file uploaded	This error is returned when ‘image’ is not sent or more than 2 images in the API call
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
413	The request is larger than the server is willing or able to process	Uploaded image too large
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request

4. Response

200 : Success

{
							 "requestId": "1651716567561-05d269b6-7e73-4b7b-8746-936a2058d566",
							 "result": {
								 "liveFace": {
									 "value": "no",
									 "to-be-reviewed": "no"
								 },
								 "qualityChecks": {
									 "blur": {
										 "value": "no",
										 "to-be-reviewed": "no"
									 },
									 "eyesClosed": {
										 "value": "no",
										 "to-be-reviewed": "no"
									 },
									 "maskPresent": {
										 "value": "yes",
										 "to-be-reviewed": "no"
									 },
									 "multipleFaces": {
										 "value": "no",
										 "to-be-reviewed": "no"
									 }
								 },
								 "summary": {
									 "action": "manualReview",
									 "details": [
										 {
											 "code": "111",
											 "message": "Selfie Not Live"
										 },
										 {
											 "code": "114",
											 "message": "Mask detected in selfie"
										 }
									 ]
								 }
							 },
							 "status": "success",
							 "statusCode": "200",
							 "transactionId": "xxxxx"
						 }

400 : Input has error

{
							 "requestId": "1651716535070-074905b6-01d7-4362-8812-39e2954db8ac",
							 "status": "failure",
							 "statusCode": "400",
							 "error": "image is required",
							 "transactionId": "xxxxxx"
						 }

401 : Unauthorization

{
							 "requestId": "",
							 "status": "failure",
							 "statusCode": "401",
							 "error": "API Key is not valid or is expired / revoked."
						 }

500 : Server error

{
							 "status": "failure",
							 "statusCode": "500",
							 "error": "Internal Server Error"
						 }

5. Quality Checks

Name	Description
Blur Detection	Detect face is blured
Eyes Closed Detection	Detect user’s eyes are closed
Mask Present Detection	Detect user wears mask
Multiple Faces Detection	Detect mutiple faces present in frame

6. Summary Details Error

Error Code	Error Message
111	Ảnh được chụp từ thiết bị khác
112	Có nhiều hơn một khuôn mặt trong ảnh chụp
113	Bạn đã nhắm mắt khi chụp ảnh
114	Khuôn mặt bị che khuất
115	Ảnh chụp chân dung bị mờ, nhòe

Recognition Service (Face Indexing and Face Search)

Prerequisite

Steps

Step 1 : Register an account at
Step 2 : Search API want to use and do the Subscribe
Step 3 : Get [API Key] and add to header of request

Variables

Name	Description
[API Key]	Authorization key, value get from subscription
[Host]	Based on environment :
	Trial : https://api-gw.sandbox.finos.asia/
	Production : https://apigw.finos.asia/

Face indexing

1. Request

Method	URL
POST	[Host]/ekyc/recognition/face/indexing_face

Header

Header	Value	Required	Note
X-FinOS-Api-Key	[API Key]	Yes
transactionId	Unique Id	No

Body

Params	Type	Required	Note
image	File	Yes	Image file
numberId	String	Yes	Identification of customer. Unique value or error 400 returned
partition	String	Yes	Unique storage space of 1 collection

2. CURL

curl --location --request POST '[Host]/ekyc/recognition/face/indexing_face' \
						 --header 'Content-Type: multipart/form-data;' \
						 --header 'Accept-Encoding: gzip, deflate, br' \
						 --header 'X-FinOS-Api-Key: [API Key]' \
						 --form 'image=@"/image.png"' \
						 --form 'numberId="1234"' \
						 --form 'partition="ABC"'

3. HTTP Status

Status Code	Error Message	Error Description	Note
400	Id number has been duplicated	Id number has been indexed before	Required re-run indexing : NO
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]	Required re-run indexing : YES
413	The request is larger than the server is willing or able to process	Uploaded image too large
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit	Required re-run indexing : YES
500	Internal Server Error	Something wrong with server when processing request	Required rerun indexing : Double check with FinOS before re-indexing
504	Gateway timeout	Connection from client to server has been timed out	Double check with FinOS before re-indexing

4. Response

200 : Success

{
							 "messages": [
								 {
									 "code": "SUCCESS",
									 "message": "Operation successful."
								 }
							 ],
							 "data": {
								 "milvusId": "431836424575779473",
								 "idNumber": "1234",
								 "facePath": "https://storage.test.finos.asia/finos-public-test-bucket/FACE_INDEXING/Finos/434922241667367011.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220730T021538Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=MINIO_ACCESS_KEY%2F20220730%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=73df23f6a8f55fd991cfaab822c3b06113dae624c97df64a51b50feba9e3f3fc ",
								 "indexingTime": "2022-07-30"
							 }
						 }

400 : Input has error

{
							 "messages": [
								 {
									 "code": "BAD_REQUEST",
									 "message": "Id number has been duplicated"
								 }
							 ],
							 "data": null
						 }

401 : Unauthorization

{
							 "requestId": "",
							 "status": "failure",
							 "statusCode": "401",
							 "error": "API Key is not valid or is expired / revoked."
						 }

500 : Server error

{
						   " messages": {
							 "code": "E9999",
							 "message": "Internal Server Error"
						   },
						   "data": null
						 }

Face Searching

1. Request

Method	URL
POST	[Host]/ekyc/recognition/face/search

Header

Header	Value	Required	Note
X-FinOS-Api-Key	[API Key]	Yes
transactionId	Unique Id	No

Body

Params	Type	Required	Note
inage	File	Yes	Image file
partition	String	Yes	Unique storage space of 1 collection. It’s must be same with partition has been indexed

2. CURL

curl --location --request POST '[Host]/ekyc/recognition/face/search' \
							 --header 'Content-Type: multipart/form-data;' \
							 --header 'Accept-Encoding: gzip, deflate, br' \
							 --header 'X-FinOS-Api-Key: [API Key]' \
							 --form 'image=@"/image.png"' \
							 --form 'partition="ABC"'

3. HTTP Status

Status Code	Error Message	Error Description
400	Invalid image file uploaded	This error is returned when ‘image’ is not sent or more than 2 images in the API call
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
413	The request is larger than the server is willing or able to process	Uploaded image too large
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request
504	Gateway timeout	Connection from client to server has been timed out

4. Response

200 : Success

{
								 "messages": [
									 {
										 "code": "SUCCESS",
										 "message": "Operation successful."
									 }
								 ],
								 "data": [
									 {
										 "milvusId": "434922241667372509",
										 "similar": 71.25461101531982,
										 "idNumber": "212706786",
										 "facePath": "https://storage.test.finos.asia/finos-public-test-bucket/FACE_INDEXING/MOVI/434922241667372509.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220802T065656Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86399&X-Amz-Credential=MINIO_ACCESS_KEY%2F20220802%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=fb4e417cde0a14e8ca74ca5be1f17c6cdae9437a43e8f7a3a17d9e4b4b6f969c",
										 "indexingTime": "2022-07-30"
									 },
									 {
										 "milvusId": "434922241667552695",
										 "similar": 68.62101703882217,
										 "idNumber": "001202007844",
										 "facePath": "https://storage.test.finos.asia/finos-public-test-bucket/FACE_INDEXING/MOVI/434922241667552695.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220802T065656Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=MINIO_ACCESS_KEY%2F20220802%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=7591a359141b014d25d970fc805887cded418c57cf283fed5d02bfb99bf4cde3",
										 "indexingTime": "2022-07-30"
									 },
									 {
										 "milvusId": "434922241667533507",
										 "similar": 68.37782263755798,
										 "idNumber": "3023464276046011",
										 "facePath": "https://storage.test.finos.asia/finos-public-test-bucket/FACE_INDEXING/MOVI/434922241667533507.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20220802T065656Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=MINIO_ACCESS_KEY%2F20220802%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=43aae937cfbb3bc8084ad5dbcd9f5c66b462fa9bf43785f2b5b523a708b5b828",
										 "indexingTime": "2022-07-30"
									 }
								 ]
							 }

400 : Input has error

{
								 "messages": [
									 {
										 "code": "BAD_REQUEST",
										 "message": "Invalid request."
									 }
								 ],
								 "data": null
							 }

401 : Unauthorization

{
								 "requestId": "",
								 "status": "failure",
								 "statusCode": "401",
								 "error": "API Key is not valid or is expired / revoked."
							 }

500 : Server error

{
							   " messages": {
								 "code": "E9999",
								 "message": "Internal Server Error"
							   },
							   "data": null
							 }

eKYC Transaction

Query eKYC Transaction

This is API specification for eKYC transaction history as a part of eKYC service provided by FinOS Technology VN.
Version : v1.0.0

1. Request

Method	URL
POST	[Host]/ekyc/transaction/history

Header

Header	Value	Required	Note
X-FinOS-Api-Key	[API Key]	Yes

Body

Params	Type	Required	Note	Example
requestIds	List<String>	Yes	List of requestId	54659be0-7697-4c12-a59b-e076977c121f,4c8c0bd5-4fcb-4a38-8c0b-d54fcbba38a4

2. CURL

curl --location --request POST '[Host]/ekyc/transaction/history' \
													 --header 'Accept-Encoding: gzip, deflate, br' \
													 --header 'X-FinOS-Api-Key: [API Key]' \
													 --form 'requestIds=[requestIds]' \

3. HTTP Status

Status Code	Error Message	Error Description
400	Param [RequestIds] cannot empty	RequestIds is a mandatory field, system used requestId for query transaction
401	API Key is not valid or is expired / revoked.	Unauthorization due to invalid [API Key]
429	Rate limit exceeded	This error is returned when the number of transactions per minute has crossed the limit
500	Internal Server Error	Something wrong with server when processing request
504	Gateway timeout	Connection from client to server has been timed out

4. Response

Response Transaction Attributes

Attribute Name	Description	Note
requestTime	Time transaction was created	Date Format : dd/MM/yyyy HH:mm:ss
apiCode	Code define transaction type	Possible value : FACE_COMPARE, OCR_NATIONALID, LIVENESS_CHECK_SERVER, RECOGNITION_FACE_INDEXING, RECOGNITION_FACE_SEARCHING
statusCode	Status code of transaction
data	Json value, the result of eKYC transaction
imagePath1	Image URL of document / selfie	Presigned URL, it’s only valid in 30 minutes
imagePath2	Image URL of document / selfie	Presigned URL, it’s only valid in 30 minutes

Response Example

200 : Success

{
							"requestId": "99580f73-0ec4-40f3-980f-730ec4c0f3b2",
							"result": {
								"details": {
									"transactions": [
										{
											"requestTime": "18/10/2022 02:35:35",
											"apiCode": "OCR_NATIONALID",
											"statusCode": "200",
											"data": "{\"status\":\"success\",\"statusCode\":\"200\",\"result\":{\"details\":[{\"fieldsExtracted\":{\"idNumber\":{\"value\":\"079090000523\",\"toBeReviewed\":\"no\"},\"name\":{\"value\":\"NGUYỄN THÀNH TÀI\",\"toBeReviewed\":\"no\"},\"dob\":{\"value\":\"12-05-1990\",\"toBeReviewed\":\"no\"},\"homeTown\":{\"value\":\"Xã Thái Hòa, Huyện Tân Uyên, Tỉnh Bình Dương\",\"toBeReviewed\":\"no\"},\"permanentAddress\":{\"value\":\"51/45 Chu Văn An, Phường 12, Quận Bình Thạnh, Thành Phố Hồ Chí Minh\",\"toBeReviewed\":\"no\",\"province\":\"Hồ Chí Minh\",\"ward\":\"12\",\"district\":\"Bình Thạnh\",\"street\":\"51/45 Chu Văn An\"},\"gender\":{\"value\":\"Nam\",\"toBeReviewed\":\"no\"},\"doe\":{\"value\":\"12-05-2030\",\"toBeReviewed\":\"no\"},\"nationality\":{\"value\":\"Việt Nam\",\"toBeReviewed\":\"no\"}},\"qualityChecks\":{\"faceNotDetected\":{\"toBeReviewed\":\"no\",\"value\":\"no\"},\"blur\":{\"value\":\"no\",\"toBeReviewed\":\"no\"},\"glare\":{\"value\":\"yes\",\"toBeReviewed\":\"no\"},\"partialID\":{\"value\":\"no\",\"toBeReviewed\":\"no\"},\"blackAndWhite\":{\"value\":\"no\",\"toBeReviewed\":\"no\"},\"capturedFromScreen\":{\"value\":\"no\",\"toBeReviewed\":\"no\"}},\"ruleChecks\":{\"idDOBGenderCodeInvalid\":{\"value\":\"no\",\"toBeReviewed\":\"no\"},\"idNumberLengthMismatch\":{\"value\":\"no\",\"toBeReviewed\":\"no\"}},\"tamperChecks\":{\"photoTampered\":{\"value\":\"\",\"toBeReviewed\":\"yes\"}},\"type\":\"cccd_chip_front\"}],\"summary\":{\"action\":\"pass\",\"details\":[]}},\"requestId\":\"0663ecf8-3cee-4ec5-851b-959effc6bb38\",\"transactionId\":\"test-postman\"}",
											"imagePath1": "https://storage.test.finos.asia/finos-public-test-bucket/ekyc-transaction/79fd6cfb-2c1f-454e-a746-c36cc39300ac/image1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20221024T100038Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86399&X-Amz-Credential=MINIO_ACCESS_KEY%2F20221024%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=6cb22d5c0b290eca1ee421b26eafb84c06b809c623ea2ce4d762fc4908b2c2c5"
										},
										{
											"requestTime": "17/10/2022 09:03:47",
											"apiCode": "FACE_COMPARE",
											"statusCode": "200",
											"data": "{\"requestId\":\"13a1e384-8d1d-4fac-a6f9-4eb49a39cc64\",\"result\":{\"conf\":1.0,\"match\":\"no\",\"matchScore\":52,\"match_score\":52,\"toBeReviewed\":\"no\"},\"status\":\"success\",\"statusCode\":\"200\"}",
											"imagePath1": "https://storage.test.finos.asia/finos-public-test-bucket/ekyc-transaction/426f346b-4ef4-4b4b-92a4-2fa7c6a3cc06/image1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20221024T100038Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86400&X-Amz-Credential=MINIO_ACCESS_KEY%2F20221024%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=33d52f684dbe45f3f30b0571eae24556bb38b985b04adf04ec279d17136c649c",
											"imagePath2": "https://storage.test.finos.asia/finos-public-test-bucket/ekyc-transaction/426f346b-4ef4-4b4b-92a4-2fa7c6a3cc06/image2.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20221024T100038Z&X-Amz-SignedHeaders=host&X-Amz-Expires=86399&X-Amz-Credential=MINIO_ACCESS_KEY%2F20221024%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Signature=4eed3d6e6639b9e7d9769f2dfc6c972d047848635f273ccf9ef5cb9b995ceec0"
										}
									]
								}
							},
							"status": "success",
							"statusCode": "200"
						}

400 : Input has error

{
								"requestId": "96b490be-94a0-469f-b490-be94a0069f4a",
								"status": "failure",
								"statusCode": "400",
								"error": "Param [RequestIds] cannot empty"
							}

401 : Unauthorization

{
								"requestId": "",
								"status": "failure",
								"statusCode": "401",
								"error": "API Key is not valid or is expired / revoked."
							}

500 : Server error

{
							"requestId": "790a3345-b773-488c-8a33-45b773b88c5b",
							"status": "failure",
							"statusCode": "500",
							"error": "Internal Server Error"
							}