KYC API Docs

KYC Service REST API Documentation

Compiled from the actual REST controllers inside `workspace/service/service/kycService`, covering user onboarding, liveness verification, and back-office review endpoints.

Back to OCR Verification Contact for integration

Base path/api/web/kycService

Response envelopeApiResponse { code, message, data }

Upload formatmultipart/form-data

Admin namespace/admin/kyc

Scanned Source

Integration overview derived from real controllers

This page is derived from the real routes in `ApiKycController`, `ApiKycLivenessController`, and `AdminKycController` instead of a generic marketing outline.

Create the profile

Call `/submit` first to obtain the `profileId` used by document upload, liveness, and status queries.

Send document data

If you already host the files, use `/document`; the recommended path is `/document/upload` for image upload, OCR, and quality checks.

Confirm and submit

Use `/document/confirm` so the user can verify extracted fields, then `/document/submit` to route the record to auto-approval or manual review.

Run liveness and poll status

The liveness flow uses `/liveness/start` and `/liveness/verify`, while `/status/{profileId}` returns the overall KYC result.

Scanned source: /workspace/service/service/kycService/src/main/java/com/sargia/finger/kycService/rest

The service also contains mirrored admin-style endpoints at `/api/web/kycService/list`, `/detail/{profileId}`, and `/status/update`, while the dedicated back-office namespace remains `/admin/kyc`.

Envelope

Shared response structure

Every scanned controller returns `ApiResponse`, with business payloads nested inside `data`.

Field	Type	Example
`code`	number	0 for success, non-zero for failures or business exceptions
`message`	string	success, query success, Document uploaded successfully, and similar messages
`data`	object	Business payload such as profileId, status, detail, or list

Core Web API

User-facing endpoints

Mapped from `ApiKycController`, covering profile creation, document upload, field confirmation, submission, and status queries.

7 documented endpoints

POST/api/web/kycService/submit

Selected endpoint

Create profile

Create a KYC profile and return the `profileId` used by all downstream calls.

PublicRecommended

Field	Type	Required	Location	Example
`userId`	string	Yes	body	user_10001
`country`	string	Yes	body	SG

Response highlights

profileId

Notes

Returns `ApiResponse.ok().data("profileId", profileId)` on success.

POST/api/web/kycService/document

Selected endpoint

Upload document metadata

Submit document metadata with image URLs or base64 references for teams that already host files.

Public

Field	Type	Required	Location	Example
`profileId`	string	Yes	body	profile_123456
`docType`	string	Yes	body	PASSPORT
`docNumber`	string	No	body	E12345678
`frontImageUrl`	string	Yes	body	https://cdn.example/front.jpg
`backImageUrl`	string	No	body	https://cdn.example/back.jpg
`expiryDate`	date	No	body	2030-12-31
`issueCountry`	string	No	body	SG

Response highlights

codemessage

Notes

The controller stores document metadata through `kycService.uploadDocument(...)`.

POST/api/web/kycService/document/upload

Selected endpoint

Upload and verify document

Upload front and back images, run OCR and quality checks, and return extracted identity fields.

PublicRecommended

Field	Type	Required	Location	Example
`profileId`	string	Yes	multipart	profile_123456
`docType`	string	Yes	multipart	ID_CARD
`country`	string	Yes	multipart	SG
`frontImage`	file	Yes	multipart	id-front.jpg
`backImage`	file	No	multipart	id-back.jpg

Response highlights

documentIdverifiednameidNumberbirthDateexpiryDatefrontQualityScorebackQualityScoreerrors

Notes

When OCR succeeds, the response includes extracted identity fields for user confirmation.
When verification fails, the controller returns `errorCode`, quality scores, and `errors`.

POST/api/web/kycService/document/confirm

Selected endpoint

Confirm extracted fields

Let the user confirm or edit OCR results before the final review step.

Public

Field	Type	Required	Location	Example
`documentId`	number	Yes	query	123456789
`name`	string	No	body	Alex Tan
`idNumber`	string	No	body	S1234567A
`birthDate`	date	No	body	1990-01-01
`expiryDate`	date	No	body	2030-12-31
`issuer`	string	No	body	ICA Singapore
`nationality`	string	No	body	SGP
`userModified`	boolean	No	body	true

Response highlights

documentIdstatusverifiedextractedInfo

Notes

If `userModified` is true, the service message indicates the record will enter manual review.

POST/api/web/kycService/document/submit

Selected endpoint

Submit document for review

Finalize the document step after user confirmation and return the review status.

Public

Field	Type	Required	Location	Example
`documentId`	number	Yes	query	123456789

Response highlights

documentIdstatusverifiederrors

Notes

The controller maps status 1, 2, and 3 to auto-approved, manual review, and user-modified review.

GET/api/web/kycService/status/{profileId}

Selected endpoint

Get verification status

Fetch the current KYC status, liveness result, and face-match information by `profileId`.

PublicRecommended

Field	Type	Required	Location	Example
`profileId`	string	Yes	path	profile_123456

Response highlights

statusstatusDescriptionkycLevelriskScorelivenessStatusfaceMatchPassed

Notes

Returns `data.status` as a `KycStatusDto` object rather than a flat primitive field.

POST/api/web/kycService/callback/liveness

Selected endpoint

Liveness callback

Server-to-server callback used to persist liveness results rather than a browser-facing endpoint.

Callback

Field	Type	Required	Location	Example
`profileId`	string	Yes	body	profile_123456
`sessionId`	string	No	body	550e8400-e29b-41d4-a716-446655440000
`confidence`	number	No	body	96.2
`result`	string	No	body	success
`errorMessage`	string	No	body	timeout

Response highlights

codemessage

Notes

`LivenessCallback.toEntity()` is currently a placeholder conversion in the scanned service code.

Liveness API

Liveness verification endpoints

Mapped from `ApiKycLivenessController`, including session creation, video verification, and session lookup.

3 documented endpoints

POST/api/web/kycService/liveness/start

Selected endpoint

Start liveness session

Create a five-minute session and return three randomized challenge actions.

PublicRecommended

Field	Type	Required	Location	Example
`profileId`	string	Yes	query	profile_123456

Response highlights

sessionIdactionsexpireTimetimeout

Notes

The controller shuffles `LivenessActionEnum` values and returns exactly three actions.

POST/api/web/kycService/liveness/verify

Selected endpoint

Verify liveness videos

Upload three challenge videos and return the aggregated liveness result.

PublicRecommended

Field	Type	Required	Location	Example
`sessionId`	string	Yes	multipart	550e8400-e29b-41d4-a716-446655440000
`profileId`	string	Yes	multipart	profile_123456
`video1`	file	Yes	multipart	blink.mp4
`video2`	file	Yes	multipart	smile.mp4
`video3`	file	Yes	multipart	turn-left.mp4

Response highlights

verifiedconfidencecompletedActionsfailedActionsmessage

Notes

Failure uses `ApiResponse.error().code(20001)` with the liveness result still returned in `data.list`.

GET/api/web/kycService/liveness/session/{sessionId}

Selected endpoint

Get liveness session

Read the current liveness session from cache and inspect its status.

Public

Field	Type	Required	Location	Example
`sessionId`	string	Yes	path	550e8400-e29b-41d4-a716-446655440000

Response highlights

sessionIdprofileIdactionsexpireTimestatuscreateTime

Notes

If the session is missing or expired, the controller returns an error message instead of null data.

Admin Review API

Back-office review endpoints

Mapped from `AdminKycController`, including list, detail, and review status updates.

3 documented endpoints

POST/admin/kyc/list

Selected endpoint

List KYC records

Query paginated KYC records for operations teams and filter by `profileIds` when needed.

Admin

Field	Type	Required	Location	Example
`profileIds`	array<string>	No	body	["profile_123","profile_456"]
`page`	number	No	body	1
`limit`	number	No	body	20

Response highlights

totalpagescurrentsizerecords

Notes

The same list capability is also mirrored in `ApiKycController` at `/api/web/kycService/list`.

GET/admin/kyc/detail/{profileId}

Selected endpoint

Get KYC detail

Fetch the full review payload for one profile, including document, liveness, and face-match data.

Admin

Field	Type	Required	Location	Example
`profileId`	string	Yes	path	profile_123456

Response highlights

detail

Notes

A mirrored detail endpoint also exists at `/api/web/kycService/detail/{profileId}`.

POST/admin/kyc/update-status

Selected endpoint

Update review status

Approve, reject, or reset the KYC review state from the admin namespace.

Admin

Field	Type	Required	Location	Example
`profileId`	string	Yes	body	profile_123456
`status`	string	Yes	body	2
`remark`	string	No	body	Manual review passed

Response highlights

codemessage

Notes

Allowed status values in the DTO are `-1`, `0`, and `2`.
The web-controller mirror path is `/api/web/kycService/status/update`.

POST/api/web/kycService/submit

Create profile

Create a KYC profile and return the `profileId` used by all downstream calls.

Example request

curl -X POST "https://api.fingerkyc.com/api/web/kycService/submit" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FINGER_KYC_TOKEN" \
  -d '{
  "userId": "user_10001",
  "country": "SG"
}'

Response highlights

profileId