KYC API Docs

KYC Service REST API Documentation

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

Back to AML pageContact 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 generated from the real routes in `ApiKycController`, `ApiKycLivenessController`, and `AdminKycController` instead of a generic marketing outline.

01

Create the profile

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

02

Send document data

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

03

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.

04

Run liveness and poll status

The liveness flow uses `/liveness/start` and `/liveness/verify`, while `/status/` 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/`, 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`.

FieldTypeExample
codenumber0 for success, non-zero for failures or business exceptions
messagestringsuccess, query success, Document uploaded successfully, and similar messages
dataobjectBusiness 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.

POST
PublicRecommended

Create profile

/api/web/kycService/submit

Create a KYC profile and return the profileId used by all downstream calls. 建立 KYC 档案并返回后续接口共用的 profileId。

FieldTypeRequiredLocationExample
userIdstringYesbodyuser_10001
countrystringYesbodySG

Response highlights

profileId

Notes

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

Upload document metadata

/api/web/kycService/document

Submit document metadata with image URLs or base64 references. 提交证件元数据，适合已有文件托管链路的接入方。

FieldTypeRequiredLocationExample
profileIdstringYesbodyprofile_123456
docTypestringYesbodyPASSPORT
docNumberstringNobodyE12345678
frontImageUrlstringYesbodyhttps://cdn.example/front.jpg
backImageUrlstringNobodyhttps://cdn.example/back.jpg
expiryDatedateNobody2030-12-31
issueCountrystringNobodySG

Response highlights

codemessage

Notes

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

Upload and verify document

/api/web/kycService/document/upload

Upload front/back images, run OCR and quality checks, and return extracted identity fields. 上传证件图片并同步返回 OCR 与质量校验结果。

FieldTypeRequiredLocationExample
profileIdstringYesmultipartprofile_123456
docTypestringYesmultipartID_CARD
countrystringYesmultipartSG
frontImagefileYesmultipartid-front.jpg
backImagefileNomultipartid-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
Public

Confirm extracted fields

/api/web/kycService/document/confirm

Let the user confirm or edit OCR results before the final review step. 用户确认或修正 OCR 字段，必要时触发人工审核。

FieldTypeRequiredLocationExample
documentIdnumberYesquery123456789
namestringNobodyAlex Tan
idNumberstringNobodyS1234567A
birthDatedateNobody1990-01-01
expiryDatedateNobody2030-12-31
issuerstringNobodyICA Singapore
nationalitystringNobodySGP
userModifiedbooleanNobodytrue

Response highlights

documentIdstatusverifiedextractedInfo

Notes

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

Submit document for review

/api/web/kycService/document/submit

Finalize the document step after user confirmation. 完成用户确认后，正式提交证件审核并返回最终状态。

FieldTypeRequiredLocationExample
documentIdnumberYesquery123456789

Response highlights

documentIdstatusverifiederrors

Notes

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

Get verification status

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

Fetch the current KYC status, liveness result, and face-match information by profileId. 查询整个 KYC 档案的当前状态。

FieldTypeRequiredLocationExample
profileIdstringYespathprofile_123456

Response highlights

statusstatusDescriptionkycLevelriskScorelivenessStatusfaceMatchPassed

Notes

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

Liveness callback

/api/web/kycService/callback/liveness

Server-to-server callback used to persist liveness results. 这是服务侧回调入口，不是前端页面直接调用的接口。

FieldTypeRequiredLocationExample
profileIdstringYesbodyprofile_123456
sessionIdstringNobody550e8400-e29b-41d4-a716-446655440000
confidencenumberNobody96.2
resultstringNobodysuccess
errorMessagestringNobodytimeout

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.

POST
PublicRecommended

Start liveness session

/api/web/kycService/liveness/start

Create a five-minute session and return three randomized challenge actions. 创建 5 分钟有效的活体动作会话。

FieldTypeRequiredLocationExample
profileIdstringYesqueryprofile_123456

Response highlights

sessionIdactionsexpireTimetimeout

Notes

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

Verify liveness videos

/api/web/kycService/liveness/verify

Upload three challenge videos and return the aggregated liveness result. 上传三个动作视频并返回活体验证结果。

FieldTypeRequiredLocationExample
sessionIdstringYesmultipart550e8400-e29b-41d4-a716-446655440000
profileIdstringYesmultipartprofile_123456
video1fileYesmultipartblink.mp4
video2fileYesmultipartsmile.mp4
video3fileYesmultipartturn-left.mp4

Response highlights

verifiedconfidencecompletedActionsfailedActionsmessage

Notes

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

Get liveness session

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

Read the current liveness session from cache and inspect its status. 查询缓存中的活体会话状态。

FieldTypeRequiredLocationExample
sessionIdstringYespath550e8400-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.

POST
Admin

List KYC records

/admin/kyc/list

Query paginated KYC records for operations teams. 后台分页查询 KYC 档案列表并支持按 profileIds 过滤。

FieldTypeRequiredLocationExample
profileIdsarray<string>Nobody["profile_123","profile_456"]
pagenumberNobody1
limitnumberNobody20

Response highlights

totalpagescurrentsizerecords

Notes

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

Get KYC detail

/admin/kyc/detail/{profileId}

Fetch the full review payload for one profile, including document, liveness, and face-match data. 获取单个 KYC 档案的完整审核详情。

FieldTypeRequiredLocationExample
profileIdstringYespathprofile_123456

Response highlights

detail

Notes

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

Update review status

/admin/kyc/update-status

Approve, reject, or reset the KYC review state from the admin namespace. 在后台审核链路中更新 KYC 状态。

FieldTypeRequiredLocationExample
profileIdstringYesbodyprofile_123456
statusstringYesbody2
remarkstringNobodyManual 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`.

Disclaimer：

Finger Trader is an infrastructure software platform designed for institutions, providing technical support at the system and data layers, and does not involve financial services, investment advice, brokerage business, or trade execution.

The information published on the website is for general reference only, not intended for specific traders, and does not constitute any financial advice.

Before making any investment decisions based on such information, you should seek advice from qualified and certified securities professionals and conduct thorough due diligence.

Any information provided by Finger Trader should not be regarded as investment advice, a solicitation to buy or sell, or an offer, nor as a recommendation, endorsement, or sponsorship of any security, company, or fund.

Finger Trader assumes no responsibility for any investment decisions you make based on such information.

All investment decisions and related research are your sole responsibility.

Finger is a software development company and does not provide any form of investment or brokerage services.

© 2026 Sargia Inc.

All rights reserved.

Address: 〒560-0011 Osaka, Toyonaka, Uenonishi, 3-chōme−2−50

Post code: 560-0011

Privacy Policy ‧ Cookies Policy