APIs in update-information flow

• This document describes the APIs of the update information flow (also known as the eKYC flow) of the FPT AI eKYC system. These APIs include:

  • Init session API
  • OCR API
  • Liveness and Face Matching API
  • NFC Data Check API
  • QR Code Information API

• Base URL

  • Staging: https://api.fpt.ai/vision/ekyc/be-stag
  • Production: https://api.fpt.ai/vision/ekyc-be

• Sequence diagram of API calls in update information flow

1. Init session API

1.1. Request Url

POST base_url/session/init

If you are using the FPT AI eKYC SDK, you should use the following URL:

POST base_url/init_session

1.2. Request Headers

Parameter	Required	Default	Description
api-key	Yes		Your API key to authorize to the system of FPT AI eKYC
client_uuid	No		The UUID generated by customer's system to manage eKYC session
device-type	Yes		Your device, values including: android ios web-sdk
only-engine	No		Set value to 1 when using only-OCR flow
sdk-version	No	String	Version of FPT AI eKYC SDK. Required to be sent to ensure optimal performance when using the SDK.

1.3. Request Sample

curl --location --request POST 'base_url/session/init' \
--header 'api-key: your-api-key' \
--header 'device-type: android' \
--header 'client_uuid: your-uuid'

1.4. Response

1.4.1. Response Sample

• Succeeded: http_code = 200

{
    "code": "200",
    "message": "success",
    "session-id": "7760a743-884b-4195-b781-892e72c7b0b6",
}

• Failed: http_code != 200

1.4.2. Response Description

Parameter	Data type	Description	Note
code	string	Response status of the request	200: Success
message	string	Error message (if any)	200: Success 401: Unauthorized 403: Forbidden 504: Gateway Timeout 500: Internal Server Error
session-id	string	The UUID of eKYC session generated by eKYC Backend. Then, this session-id must be sent in headers of all following requests in the same session

2. OCR API

2.1. Request Url

POST base_url/ocr

2.2. Request Headers

Parameter	Required	Data type	Description	Note
session-id	Yes	String	Session id get from init session request
api-key	Yes	String	Your API key to authorize to the system of FPT AI eKYC
device-type	Yes	String	Your device, values including: android ios web-sdk
document-type	Yes	String	Type of using document. There are 3 types supported: Identity card: idr Passport: passport Driving License: dlr
side-type	No	String	This option is intended for cases where the client prefers each side of the ID to be sent to eKYC server for processing immediately after capture, rather than waiting until both sides have been collected. The values including: front back Noted that image of front side must be sent first.
lang	No	String	Using language, values including: en vi	default: en
get-detail-response	No	String	Include the AI model's raw data in the returned result (within the detail_response field).	Value 1: Including the raw output data of the AI model in the response If set to any other value or if this header is not provided, the raw data is not included
sdk-version	No	String	Version of FPT AI eKYC SDK. Required to be sent to ensure optimal performance when using the SDK.

2.3. Request Body

FormData containing the images for the query. The front side image must be provided before the back side image. If document-type is passport or using side-type in headers, there should be only 1 image provided to the system in each request.

Parameter	Required	Value	Description
files	Yes	path-to-image	Captured image of front side of document
files	Yes	path-to-image	captured image of back side of document

2.4. Request Sample

curl --location --request POST 'base_url/ocr' \
--header 'api-key: your api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'device-type: android' \
--header 'document-type: idr' \
--header 'lang: vi' \
--form 'files=@"path-to-front.jpg"' \
--form 'files=@"path-to-back.jpg"'

2.5. Response

2.5.1. Response Sample

• Succeeded

{
    "errorCode": "0",
    "errorMessage": "",
    "data": [
        {
            "key": "ID",
            "name": "Số/ No",
            "value": "xxxxx",
            "score": "98.66",
            "locale": "vn"
        },
        {
            "key": "Name",
            "name": "Họ và tên",
            "value": "your name,
            "score": "99.71",
            "locale": "vn"
        },
        {
            "key": "Date of birth",
            "name": "Ngày sinh",
            "value": "dd/mm/yyyy",
            "score": "98.41",
            "locale": "vn"
        },
        {
            "key": "Sex",
            "name": "Giới tính",
            "value": "NAM",
            "score": "98.30",
            "locale": "vn"
        },
        {
            "key": "Nationality",
            "name": "Quốc tịch",
            "value": "VIỆT NAM",
            "score": "99.77",
            "locale": "vn"
        },
        {
            "key": "Home",
            "name": "Quê quán",
            "value": "X, Y NAM ĐỊNH",
            "score": "96.54",
            "locale": "vn"
        },
        {
            "key": "Address",
            "name": "Địa chỉ",
            "value": "X, Y NAM ĐỊNH",
            "score": "98.27",
            "locale": "vn"
        },
        {
            "key": "Expired Date",
            "name": "Ngày hết hạn",
            "value": "dd/mm/yyyy",
            "score": "98.93",
            "locale": "vn"
        },
        {
            "key": "Type",
            "name": "Loại",
            "value": "7",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Province",
            "name": "Tỉnh/Thành Phố",
            "value": "NAM ĐỊNH",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "District",
            "name": "Quận/ Huyện",
            "value": "Y,
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Ward",
            "name": "Phường/Xã",
            "value": "X",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Features",
            "name": "Đặc điểm nhận dạng",
            "value": "SẸO CHẤM ,
            "score": "99.78",
            "locale": "vn"
        },
        {
            "key": "Issue Date",
            "name": "Ngày cấp",
            "value": "dd/mm/yyyy",
            "score": "99.31",
            "locale": "vn"
        },
        {
            "key": "Issue Location",
            "name": "Nơi cấp",
            "value": "CỤC TRƯỞNG CỤC CẢNH SÁT QUẢN LÝ HÀNH CHÍNH VỀ TRẬT TỰ XÃ HỘI",
            "score": "95.40",
            "locale": "vn"
        }
    ],
    "total_data": []
}

2.5.2. Response Description

Fields	Types	Description	Note
errorCode	Integer	Error code returned from server. errorCode = 0 means the request success. Otherwise request has an error.	Details can be found in the document error code
errorMessage	String	Error message of the request (if any). Language of message is set by parameter lang in headers
data	Object	This object contains OCR result

2.5.3. Response Error Samples

• Session expired: Return when session is invalid such as: not registered, timeout, not match with device type,..

{
    "errorCode": "403",
    "errorMessage": "Phiên làm việc đã hết hạn"
}

• OCR error

{
    "errorCode": "3",
    "errorMessage": "Không tìm thấy tài liệu đã chọn trong ảnh"
}

3. Face Liveness and Face Match API

3.1. Request Url

POST base_url/face/liveness

3.2. Request Headers

Parameter	Required	Data type	Description	Note
session-id	Yes	String	Session id get from init session request
api-key	Yes	String	Your API key to authorize to the system of FPT AI eKYC
auto	No	string	Set value to True when call from FPT SDK. Otherwise, False
device-type	Yes	string	Your device, values including: android ios web-sdk
lang	optional	string	Using language, values including: en vi	default: en
sdk-version	No	String	Version of FPT AI eKYC SDK. Required to be sent to ensure optimal performance when using the SDK.

3.3. Request Body

FormData containing the selfies image or video to query.

Parameter	Required	Type	Description
selfies	No. Using selfies or video	Array	Selfie image captured to check liveness and do face matching
video	No. Using selfies or video	File	Selfie video captured to check liveness and do face matching

3.4. Request Sample

curl --location --request POST 'base_url/face/liveness' \
--header 'api-key: your-api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6'
--header 'device-type: android' \
--header 'lang: vi' \
--form 'selfies=@"path-to-selfie-image"' \

3.5. Response

3.5.1. Response Sample

• Succeeded

{
    "code": "200",
    "message": "Kiểm tra thực thể sống thành công",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A",
    },
    "face_match": {
        "code": "200",
        "message": "face matching successful",
        "isMatch": "true",
        "similarity": "95.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

3.5.2. Response Description

Fields	Types	Description	Note
code	String	Response status code of the request. Code 200 means request success.	Details can be found in the document error code
message	String	Error message of the request (if any). Language of message is set by parameter lang in headers
liveness	Object	returned liveness result
face_match	Object	returned face match result
is_complete_session	boolean	Define whether session is completed. If False, user can retry with face verify, otherwise, users have to try with another session

3.5.3. Response Error Samples

• Face not matching with document: Return when the face in selfie image does not match with the face in document image.

{
    "code": "303",
    "message": "Khuôn mặt không khớp với giấy tờ",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A",
    },
    "face_match": {
        "code": "303",
        "message": "face is not matching with document",
        "isMatch": "false",
        "similarity": "5.84",
        "warning": "N/A"
    },
    "is_complete_session": false
}

• 2 faces exist: Return when the system detects more than one face in selfie image.

{
    "code": "407",
    "message": "2 faces exist",
    "liveness": {
        "code": "200",
        "message": "liveness check successful",
        "is_live": "true",
        "spoof_prob": "N/A",
        "need_to_review": "N/A",
        "is_deepfake": "N/A",
        "deepfake_prob": "N/A",
        "warning": "N/A",
    },
    "face_match": {
        "code": "407",
        "message": "2 faces exist",
        "isMatch": "N/A",
        "similarity": "N/A",
        "warning": "N/A"
    },
    "is_complete_session": false
}

4. NFC-data-check API

4.1. Request Url

POST base_url/check_chip

4.2. Request Headers

Parameter	Required	Data type	Description	Note
session-id	Yes	String	Session id get from init session request
api-key	Yes	String	Your API key to authorize to the system of FPT AI eKYC
auto	Yes	string	Set value to True when call from FPT SDK. Otherwise, False
device-type	Yes	string	Your device, values including: android ios
lang	optional	string	Using language, values including: en: English vi: Vietnamese	default: en
sdk-version	No	String	Version of FPT AI eKYC SDK. Required to be sent to ensure optimal performance when using the SDK.

4.3. Request Body

Parameter	Required	Type	Description
dg1	Yes	String base64	MRZ information
dg2	Yes	String base64	Portrait photo
dg3	Yes	String base64	Left fingerprint
dg4	Yes	String base64	Right fingerprint
dg5	Yes	String base64	Unused memory area
dg6	Yes	String base64	Unused memory area
dg7	Yes	String base64	Unused memory area
dg8	Yes	String base64	Unused memory area
dg9	Yes	String base64	Unused memory area
dg10	Yes	String base64	Unused memory area
dg11	Yes	String base64	Unused memory area
dg12	Yes	String base64	Unused memory area
dg13	Yes	String base64	Basic citizen information
dg14	Yes	String base64	Contains security options for additional security mechanisms
dg15	Yes	String base64	Stored public key
dg16	Yes	String base64	Unused memory area
sod	Yes	String base64	Digital signature
challenge	Yes	String base64
aAResult	Yes	String base64	Random challenge (byte array [8] sent to NFC Chip for Active Authentication)
eACCAResult	Yes	String base64
com	Yes	String base64
expired-date	No	String	Expiration date
father	No	String	Father's name
features	No	String	Identifying characteristics
home	No	String	Place of origin
id	No	String	Citizen ID number
issue-date	No	String	Issue date
mother	No	String	Mother's name
name	No	String	Name
nation	No	String	Country
nationality	No	String	Nationality
prev-number	No	String	Old ID card number
religion	No	String	Religion
sex	No	String	Sex
address	No	String	Address
face	No	String base64	Portrait photo
qrcode	No	String	QR code

4.4. Request Sample

curl --location --request POST 'base-url/check_chip' \
--header 'api-key: your api key' \
--header 'session-id': 'your session id' \
--header 'device-type': 'android'\
--header 'lang': 'vi'\
--header 'Content-Type: application/json' \
--data '{
    "dg1": "...",
    "dg2": "...",
    "dg3": "...",
    ...
}'

4.5. Response

4.5.1. Response Sample

• Succeeded

{
    "errorCode": "0",
    "errorMessage": "",
    "valid": false,
    "verifyCode": 2,
    "verifyMessage": "Chưa xác thực thông tin C06",
    "rar_request_id": "N/A",
    "data": [
        {
            "key": "ID",
            "name": "Số/ No",
            "value": "xxxxxxxxxxx",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "PrevID",
            "name": "Số định danh trước kia",
            "value": " xxxxxxxxxxx ",
            "score": "N/A",
            "locale": "vn"
        },
        {
            "key": "Name",
            "name": "Họ & tên",
            "value": "Phạm Hoàng Tùng",
            "score": "N/A",
            "locale": "vn"
        },
        ...
    ]
}

4.5.2. Response Description

Fields	Types	Description	Note
errorCode	String	Error code returned from server. errorCode = 0 means the request success. Otherwise request has an error.	Details can be found in the document error code
errorMessage	String	Error message of the request (if any). Language of message is set by parameter lang in headers
valid	Boolean	True: RAR verification has been successful False: RAR verification has not been performed
verifyCode	String	1: Verification is successful 0: Verification is failed 2: not verify yet
verifyMessage	String	Verification message

5. QR Code API

5.1. Request Url

POST base_url/qrcode

5.2. Request Headers

Parameter	Required	Data type	Description	Note
session-id	Yes	String	Session id get from init session request
api-key	Yes	String	Your API key to authorize to the system of FPT AI eKYC
device-type	Yes	String	Your device, values including: android ios web-sdk
lang	No	String	Using language, values including: en vi	default: en
sdk-version	No	String	Version of FPT AI eKYC SDK

5.3. Request Body

Parameter	Required	Type	Description
qrcode	Yes	String	QR code data

5.4. Request Sample

curl --location --request POST 'base_url/qrcode' \
--header 'Content-Type: application/json' \
--header 'api-key: your api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'device-type: android' \
--header 'lang: vi' \
--data-raw '{
"qrcode": "0461990xxxxx|xxxxxxx|Nguyễn Văn A|060619.....
}'

5.5. Response

5.5.1. Response Sample

• Succeeded

{
    "errorCode": "0",
    "errorMessage": ""
}

• Failed

  • Expired session: Return when session is invalid such as: not registered, timeout, not match with device type, etc.

    {
        "errorCode": "403",
        "errorMessage": "Phiên làm việc đã hết hạn"
    }

  • QRcode error:

    {
        "errorCode": "QR01",
        "errorMessage": "Dữ liệu trong mã QR không khớp"
    }

5.5.2. Response Description

Fields	Types	Description	Note
errorCode	String	Error code returned from server. errorCode = 0 means the request success. Otherwise request has an error.	Details can be found in the document error code
errorMessage	String	Error message of the request (if any). Language of message is set by parameter lang in headers

6. Logging & Tracing API

This API is designed for SDK-side logging and exception tracing.
Normally, the SDK does not send any data. Logging will only be enabled when the server configuration explicitly allows it.

• During the init_session API, the server may return a flag:

  { "enable_tracing": true }

• If enable_tracing = true, the SDK should begin sending logs and exceptions to this endpoint.

• If enable_tracing = false (or the flag is absent), the SDK must not send any logging data.

This mechanism ensures that logging is only activated in debugging or error scenarios, helping developers capture detailed traces without unnecessary overhead during normal operation.

6.1. Request Url

POST base_url/logging/tracing

6.2. Request Headers

Parameter	Required	Data type	Description	Note
session-id	No	String	Session id get from init session request
api-key	Yes	String	Your API key to authorize to the system of FPT AI eKYC
device-type	No	String	Your device, values including: android ios web-sdk Should be included if logs are sent from multiple clients
lang	No	String	Using language, values including: en vi Should be included if logs are sent from multiple clients	default: en
sdk-version	No	String	Version of FPT AI eKYC SDK. Should be included if logs are sent from multiple clients
Content-Type	Yes	String	Specifies the media type of the request body	Must be application/json

6.3. Request Body

Field	Type	Required	Description
event	string	No	Event name or action (e.g., face.liveness.start).
level	string	No	Log level: debug, info, warn, error, fatal.
message	string	No	Human-readable message.
timestamp	string (ISO 8601)	No	Client-side event time; server will set one if missing.
duration_ms	number	No	Duration in milliseconds for timed operations.
attributes	object	No	Custom key–value pairs (e.g., device info, user context).
session_meta	object	No	Extra session metadata (e.g., { sdk: "android", version: "1.2.3" }).
trace_id	string	No	Correlation ID for distributed tracing.
span_id	string	No	Span ID within the trace (if supported).
exception	object	No	Exception/error details (see below).

Exception object

Field	Type	Required	Description
type	string	No	Exception type/class name (e.g., NullPointerException).
message	string	No	Exception message.
stacktrace	string	No	Full stack trace as a string.
file	string	No	Source file where the error occurred.
line	number	No	Line number of the error.
code	string	No	Error code if available.
handled	boolean	No	true if exception was caught/handled, false otherwise.
detail	object	No	Free-form JSON object with additional info (SDK can push anything).

6.4. Request Sample

curl --location --request POST '<base_url>/logging/tracing' \
--header 'api-key: your-api-key' \
--header 'session-id: 7760a743-884b-4195-b781-892e72c7b0b6' \
--header 'Content-Type: application/json' \
--data '{
  "event": "face.match",
  "level": "error",
  "message": "Face match failed on SDK",
  "timestamp": "2025-10-03T04:15:23.412Z",
  "attributes": {
    "device_type": "android",
    "os_version": "14",
    "sdk_version": "2.4.0"
  },
  "exception": {
    "type": "IllegalArgumentException",
    "message": "Invalid image format",
    "stacktrace": "com.fpt.sdk.FaceMatch.process(FaceMatch.java:102)\ncom.fpt.sdk.MainActivity.onResult(MainActivity.kt:45)",
    "file": "FaceMatch.java",
    "line": 102,
    "handled": true,
    "detail": {}
  }
}'

6.5. Response

6.5.1. Response Sample

• Succeeded

http_code = 200

{
    "code": "200",
    "message": "Success"
}

• Failed

http_code != 200