Database Validation (IDN)

Call this API to verify an Indonesian National ID (NIK) against the authoritative database with a pure API integration. The verification compares the submitted identity attributes and biometric data against the registry record.

Get an access token: Token Authentication API
Prepare a unique bizId for the business transaction
Prepare a unique userId for the user being verified
Set region to IDN, numberType to NIK, and provide numberValue (16-digit NIK)
Provide data.fullName, data.birthday, data.phoneNumber, and data.faceImage (required); data.ktpImage and data.email are optional

Request Example:

curl -X POST \
  https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/api/database-id-verification \
  -H 'Content-Type: application/json' \
  -H 'X-ACCESS-TOKEN:{Your Access Token}' \
  -d '{
    "bizId": "biz_idn_001",
    "userId": "user_idn_001",
    "region": "IDN",
    "numberType": "NIK",
    "numberValue": "1234567890123456",
    "data": {
      "fullName": "BUDI SANTOSO",
      "birthday": "1990/01/01",
      "phoneNumber": "+6281234567890",
      "email": "[email protected]",
      "faceImage": "{base64-encoded JPEG/PNG selfie}",
      "ktpImage": "{base64-encoded JPEG/PNG KTP photo — optional}"
    }
  }'

Request Url

https://sg-api.advance.ai/intl/openapi/identity-risk/idvs-h5/ekyc/v1/api/database-id-verification
POST (application/json)

Request Header Parameters

Parameter	Description
X-ACCESS-TOKEN	`string` Please use Token Authentication API to get your access token.

Request Parameters

Parameter	Description
bizId	`string` The unique business ID for the transaction that triggered this verification, such as an order ID. Must be non-empty and no longer than 99 characters.
userId	`string` The unique user ID for the user performing the verification. Must be non-empty and no longer than 200 characters.
region	`string` The supported service region. Refer to ISO ALPHA-3 Country Code. For Indonesia NIK verification, must be `IDN`.
numberType	`string` The identity number type. Case-sensitive — must be uppercase. See Supported numberType. Any value not in the supported set (or lowercase such as `nik`) will be rejected with `PARAMETER_ERROR` / `Number type and country are not match`.
numberValue	`string` Required. Indonesian NIK (Nomor Induk Kependudukan). Must be exactly 16 pure digits with the first digit non-zero (`[1-9]\d{15}`). Separators such as `-` or spaces are not accepted and will be rejected with `PARAMETER_ERROR` / `Invalid ID number，please check the format`.
data	`object` Extended data object for additional verification parameters.
data.fullName	`string` Required. Full legal name as registered on the NIK.
data.birthday	`string` Required. Date of birth in `yyyy/MM/dd` format.
data.phoneNumber	`string` Required. Mobile phone number. Must start with `+628` followed by 9–13 digits (total string length 13–17 characters).
data.faceImage	`string` Required. Base64-encoded selfie image for face matching. See Image requirements below.
data.ktpImage	`string` (optional) Base64-encoded KTP (ID card) photo. When the field is present it must be non-empty and valid. See Image requirements below.
data.email	`string` (optional) Email address. When provided, must contain both `@` and `.`.

Supported numberType

numberType	region	numberValue format	Description
NIK	IDN	Exactly 16 digits; first digit must be 1–9 (`1234567890123456`)	Indonesia National ID (NIK number)

Image requirements

Both data.faceImage and data.ktpImage (when provided) must satisfy all of the following:

Field	Format	Decoded size (bytes)	Dimensions (pixels)
faceImage	JPEG / JPG / PNG	30 KB – 1 MB	400×400 – 4096×4096
ktpImage	JPEG / JPG / PNG	≥ 1 byte – 1 MB	256×256 – 4096×4096

Images must be supplied as raw base64 strings (no data:image/...;base64, prefix). Invalid base64, unsupported format, or out-of-range size/dimension will be rejected with PARAMETER_ERROR and a field-specific message (see Top-level code below).

Response Description

Parameter	Description
code	Response Code.
transactionId	The request ID of this API call. The max length is 64.
pricingStrategy	`Deprecated`, always returns `FREE`.
message	Status Code Explanation.
data	`object` The business result of the verification.

Response.data

Field	Description
signatureId	The business ID of this verification.
overallResult	Overall verification result. One of `PASS` or `FAIL`.
errorCode	Business-level error code when `overallResult` is not `PASS`. Returns an empty string when `overallResult` is `PASS`. Possible values: `NUMBER_NOT_EXIST`, `NAME_NOT_MATCH`, `BIRTHDAY_NOT_MATCH`, `FACE_NOT_MATCH`, `ERROR`.
docDatabaseDetail	`object` Per-field match indicators returned by the database when `overallResult` is `PASS`. Returns `null` for non-`PASS` outcomes. Does not contain PII — no name, phone, email, or image data is echoed.

Response.data.docDatabaseDetail

Returned only when overallResult is PASS. Each field is a boolean indicating whether the submitted value matched the registry record for that attribute.

Field	Description
numberValue	`boolean` Whether the submitted NIK matched the registry.
fullName	`boolean` Whether the submitted full name matched.
birthday	`boolean` Whether the submitted date of birth matched.
faceResult	`boolean` Whether the submitted face image matched.

Privacy note: Unlike other country variants, the Indonesia NIK response intentionally exposes only boolean match flags. Email, phone number, and image payloads submitted in the request are never returned in the response.

Response.code

This API returns two layers of status codes. The top-level code reflects infrastructure-level, request-level validation failures. Business verification results (registry mismatches) are returned in data.overallResult and data.errorCode when the top-level code is SUCCESS.

For Indonesia NIK verification, downstream format failures are surfaced as top-level PARAMETER_ERROR (with a specific message) rather than SUCCESS + data.errorCode = INVALID_FORMAT.

Top-level `code`

Status Code	Message
SUCCESS	OK. The request reached business processing. The actual verification result is returned in `data.overallResult` and `data.errorCode`.
PARAMETER_ERROR	BizId is wrong
	BizId is too long
	UserId is invalid
	The userId length cannot exceed 200.
	Region is wrong
	Number type is empty
	Number type is wrong
	Number type and country are not match (`numberType` not in supported set for the region, or not uppercase, or `region`/`numberType` combination not allowed for IDN)
	Invalid ID number，please check the format (`numberValue` is missing, or not exactly 16 digits with a non-zero leading digit)
	Invalid name (`data.fullName` is missing or empty)
	Invalid birthday (`data.birthday` is missing, not `yyyy/MM/dd`, or not a valid calendar date)
	Invalid phone (`data.phoneNumber` is missing or does not match `+628` + 9–13 digits)
	Invalid email (`data.email` is present but does not contain both `@` and `.`)
	Invalid face image (`data.faceImage` is missing, invalid base64, wrong format, or out-of-range size/dimension)
	Invalid KTP (`data.ktpImage` is present but empty, invalid base64, wrong format, or out-of-range size/dimension)
IAM_FAILED	IAM check failed
ERROR	Server error

data.errorCode

This section applies only when the top-level code is SUCCESS.

errorCode	overallResult	Description
""	PASS	Database lookup succeeded and all submitted attributes matched. `docDatabaseDetail` contains the per-field boolean match flags.
NUMBER_NOT_EXIST	FAIL	The submitted NIK was not found in the registry. `docDatabaseDetail` is `null`.
NAME_NOT_MATCH	FAIL	The submitted full name does not match the registry record. `docDatabaseDetail` is `null`.
BIRTHDAY_NOT_MATCH	FAIL	The submitted date of birth does not match the registry record. `docDatabaseDetail` is `null`.
FACE_NOT_MATCH	FAIL	The submitted face image does not match the registry record. `docDatabaseDetail` is `null`.

Response Examples

SUCCESS

pass

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "signatureId": "a1b2c3d4e5f6g7h8",
        "overallResult": "PASS",
        "errorCode": "",
        "docDatabaseDetail": {
            "numberValue": true,
            "fullName": true,
            "birthday": true,
            "faceResult": true
        }
    },
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

name mismatch

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "signatureId": "a1b2c3d4e5f6g7h8",
        "overallResult": "FAIL",
        "errorCode": "NAME_NOT_MATCH",
        "docDatabaseDetail": null
    },
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

number not exist

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "signatureId": "a1b2c3d4e5f6g7h8",
        "overallResult": "FAIL",
        "errorCode": "NUMBER_NOT_EXIST",
        "docDatabaseDetail": null
    },
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

birthday mismatch

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "signatureId": "a1b2c3d4e5f6g7h8",
        "overallResult": "FAIL",
        "errorCode": "BIRTHDAY_NOT_MATCH",
        "docDatabaseDetail": null
    },
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

face mismatch

{
    "code": "SUCCESS",
    "message": "OK",
    "data": {
        "signatureId": "a1b2c3d4e5f6g7h8",
        "overallResult": "FAIL",
        "errorCode": "FACE_NOT_MATCH",
        "docDatabaseDetail": null
    },
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

PARAMETER_ERROR

invalid NIK number

{
    "code": "PARAMETER_ERROR",
    "message": "Invalid ID number，please check the format",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

required field missing (`fullName` / `birthday` / `phoneNumber` / `faceImage`) or invalid format

{
    "code": "PARAMETER_ERROR",
    "message": "Invalid name",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

{
    "code": "PARAMETER_ERROR",
    "message": "Invalid birthday",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

{
    "code": "PARAMETER_ERROR",
    "message": "Invalid phone",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

{
    "code": "PARAMETER_ERROR",
    "message": "Invalid face image",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

{
    "code": "PARAMETER_ERROR",
    "message": "Invalid KTP",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

{
    "code": "PARAMETER_ERROR",
    "message": "Invalid email",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

bizId is wrong

{
    "code": "PARAMETER_ERROR",
    "message": "BizId is wrong",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

bizId is too long

{
    "code": "PARAMETER_ERROR",
    "message": "BizId is too long",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

userId is invalid

{
    "code": "PARAMETER_ERROR",
    "message": "UserId is invalid",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

userId is too long

{
    "code": "PARAMETER_ERROR",
    "message": "The userId length cannot exceed 200.",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

region is wrong

{
    "code": "PARAMETER_ERROR",
    "message": "Region is wrong",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

numberType is empty

{
    "code": "PARAMETER_ERROR",
    "message": "Number type is empty",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

number type and country are not match

{
    "code": "PARAMETER_ERROR",
    "message": "Number type and country are not match",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

IAM_FAILED

{
    "code": "IAM_FAILED",
    "message": "IAM check failed",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}

ERROR

{
    "code": "ERROR",
    "message": "Server error",
    "data": null,
    "extra": null,
    "transactionId": "a1b2c3d4e5f6g7h8",
    "pricingStrategy": "FREE"
}