[SG] Document-based verification
Learn how to initiate and execute the identity verification workflow for individual account holders. This guide walks you through the steps to submit user data and facilitate the validation process within the system.
Note:
Please be aware that this feature is subject to regional availability. Before it can be enabled for your users, a specific change to your program's configuration is also required. The feature cannot be activated until both the regional and configuration prerequisites are met. Reach out to your MatchMove Implementation or Sales team to confirm availability in your area and begin the setup process.
Use Cases
- You want to submit the required KYC documents needed to verify the identity of an individual user.
- You want to submit supporting documents that will help in the individual user identity verification.
- You want to implement a feature in your application that will allow individual users to upload documents using the available MatchMove eKYC Provider.
- You want to implement a feature in your application that will allow individual users to upload supporting documents using the available MatchMove KYC endpoints.
- The individual user will submit KYC by going through the automated eKYC interface to collect selfies and identification documents.
- The individual user will submit KYC through the eKYC interface with an automated approval (no manual intervention required) mechanism.
Prerequisites
- The individual user profile must already be completed. Refer to the Register individual profile (v2) section for more details.
- The individual user profile must be in
status = pending_activation. - The individual user profile has a
kyc_status = not_submitted, indicating that they have not attempted to perform KYC yet, or - The individual user profile has a
kyc_status = pendingand akyc_sub_status = pending_document_submission, indicating that they are still required to submit document, or - The individual user profile has a
kyc_status = completedand akyc_sub_status = rejected, indicating that their previous submission was rejected.
API Workflow
1
Check if an individual user is allowed to submit KYC
Before we allow a user to submit their KYC documents, we first need to check their current KYC status. This means that when the KYC status of the user is not in the list below, the entry point or screen to initiate KYC submission must also be hidden from the partner app interface.
A user can only send a KYC submission for verification if they have the following:
|
| The User has not yet attempted to submit his KYC |
|
| The User has attempted to submit his KYC but is still required to submit other documents. |
|
| The User has attempted to submit his KYC and has failed on his last submission. |
Get Individual User
Call Get Individual User (GET /users) to retrieve the User and KYC status of an individual user.
Get Individual User request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'
Get Individual User response
{
..
"status": "pending_activation",
"sub_status": "document_submission_required",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
..
}
2
[Optional] Check if user is eligible for document-based verification
By default, document-based verification is automatically enabled for all programs.
You only need to call this API to check for other eligible methods if you have explicitly enabled additional verification options (such as authentication-based verification or partner-assisted verification) in your program configuration.
List KYC Verification Modes
Call Get KYC Verification Modes (GET /v2/users/authentications/documents/verification_modes) to get all available verification modes available for the program and applicable to the user.
List KYC Verification Modes request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verification_modes' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'
List KYC Verification Modes response
{
"verification_modes": [
{
"mode": "document_based"
},
{
"mode": "authentication_based"
}
]
}
The response will list all the verification modes that the user is eligible to undergo. If document_based is listed, then you can start to initiate the verification by requesting a KYC verification link.
3
Retrieve the eKYC redirect link to the document collection screen
The eKYC document collection page is a standalone web app. Partners must present the eKYC web app to the customer by rendering it in an in-app or external web browser. Customers can then proceed to perform eKYC by sending their selfie picture and required identity documents.
Initiate KYC Capture (Individual User)
Call Initiate KYC Capture (Individual User) (POST /users/authentications/documents/verifications) to get the href or the redirect link to the eKYC web app. To redirect users back to your application after they complete or exit the eKYC flow, include the following callback parameters in your request.
Callback Parameters (eKYC capture screen back to your app)
redirect_url: The fully qualified callback URL to which the user is redirected upon exiting or completing the eKYC flow.redirect_mode: The method of redirection. Accepted values are auto (immediate redirection upon completion) or button (requires explicit user interaction to trigger the redirect).redirect_text: The custom label displayed on the redirection button (e.g., "Exit" or "Return"). Applicable only when redirect_mode is set to button.
Initiate KYC Capture (Individual User) request
curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents/verifications' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Authorization: ••••••'
--header 'Content-Type: application/json' \
--data '{
"verification_mode":"document_based",
"redirect_url":"www.partner-callback.com",
"redirect_mode": "button",
"redirect_text": "Exit"
}'
Initiate KYC Capture (Individual User) response
{
"id": "caa61227979e43fea38d2730c11e8667",
"links": [
{
"href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1daa8fd49e7071daa9bd429dc30432dc4039e7fd067669330db4f6e89320d65554474c2b4fdace25920a30599578fcf519de4e74d2db7167e3187c83eeeb8141916b5c800b9eb2ef7485182ef21046a8f71a045c8cf8839988519bd6bddacf06eb3dd0ad5f837d40b40fd5c6cbba246ae60d74b1925f913c4ac339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7727f8205e0b0bc7f5d75f9fe85ab14b568512e2dc2e7a1d403e52f0026e93d063b8e26f73985e5b3bd968a590d54f3b08be8a3f09744206a7916ea2aee896864871bdfc41ad223efe14b2e7b77b59ef8f0f7268f32e0b5e3b1d0de123fedf957d0353de5168c9ac9c17603b44358cda2cb7a43317sd9dd844de4de81ff951&user_id=&auth_token=",
"method": "GET",
"rel": "capture.sdk"
}
],
"sub_type": "individual",
"type": "users",
"verification_id": "vfc_29baeb0da5144c678c1adf7eic61381e",
"verification_mode": "document_based"
}
The Initiate KYC Capture (Individual User) API response will return a capture link that you will need to render and display to an in-app browser (mobile app) or any browser (web app) for your customer. From here, the customer can perform the KYC document capture and submit the KYC application.
The eKYC verification is asynchronous; some background processing needs to be completed before the approval/rejection can be given.
Usually, an automated eKYC verification turnaround time will take from an instant to a few minutes, provided that all document submissions are clear and legible and the partner profile aligns perfectly with the document data.
4
Monitor for the approval of the submitted KYC
The KYC verification turnaround time follows an SLA from submission to approval.
If the partner wants to be notified when KYC approval/rejection is given, they must subscribe to the “KYC Service Advisory” webhook category and events. If a failure or rejection happens, the webhook payload will contain a reason for rejection.
Go to the Leverage Webhooks section to learn more about setting up the webhooks.
KYC Service Advisory webhooks
Partners have the option to subscribe to the webhook events related to KYC approval.
USER.STATUS | User and KYC Status Update A notification is sent in the event that the User or KYC status of the business user gets updated. | Handle User and KYC status changes as outlined in the Individual eKYC - KYC and Individual User State Transition Updates section. |
ASSOCIATED_PARTIES.PROFILE.STATUS | Associated Party KYC Status Update A notification is sent in the event that the associated parties' statuses of the business user get updated. | Handle Associated Party (Individual) status changes as outlined in the Individual eKYC - KYC and Individual User State Transition Updates section. |
Deprecation notice: | KYC Document Verification Update A notification is sent in the event that the KYC status of the business user is updated to either approved or rejected. | [Approved] No action required. [Rejected] You may ask the user to retry or redo another round of KYC submission. |
Deprecation notice: | KYC Document Verification Update - Associated Party | [Approved] No action required. [Rejected] You may ask the associated party to retry or redo another round of KYC submission. |
USER.STATUS (Approved) sample webhook payload
ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS
{
"entities": {
"user": {
"addresses": {
"billing": {
"city": "ABORLAN_PALAWAN",
"country": "Denmark",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "4107",
"state": "Cavite",
"state_code": "123"
},
"foundation": {},
"identity_verification": {},
"operational": {},
"residential": {
"city": "GABALDON_BITULOK_SAB",
"country": "Germany",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "2200",
"state": "LAUNION",
"state_code": "123"
},
"shipping": {
"city": "ABORLAN_PALAWAN",
"country": "Denmark",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "4107",
"state": "Cavite",
"state_code": "123"
}
},
"agent_id": "",
"alias_name": "ncmxnc",
"annual_income_range": "20000",
"birth": {
"city": "Gen Trias",
"country": "Singapore",
"date": "2000-04-02",
"name": "John Smith",
"postal_code": "1000"
},
"client_ref_id": "9234567891",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2026-08-12T20:04:20Z",
"date_updated": "2026-08-12T20:09:48Z",
"email": "test@matchmove.com",
"employment_details": {
"business_address": {
"city": "ABORLAN_PALAWAN",
"country": "Denmark",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "4107",
"state": "Cavite"
},
"business_purpose": "ACCOUNTING",
"business_trading_name": "abcdefg",
"expected_monthly_revenue": "1000000",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "Manila",
"vat_number": "893678372"
},
"employment_type": "Self Employed",
"ethnicity": "ncmxnc",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {
"first_name": "Steve",
"last_name": "Smith",
"maiden_name": "v c m",
"middle_name": ""
},
"first_name": "Testerqnq",
"gender": "Male",
"http_status_code": 0,
"id": "560b71f5e4904195a0bbd8a37020881b",
"identification": {
"primary": {
"id_date_expiry": "2030-02-12",
"id_date_issued": "2025-06-08",
"id_issuance_country": "Spain",
"id_number": "02345678A",
"id_type": "Id Card",
"metadata": "{\"mrzLine1\":\"IDESPAAA023456789026070A\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\",\"mrzLine2\":\"3456789M5678901234\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c0\",\"mrzLine3\":\"CITIZEN\\u003cSMITH\\u003c\\u003cAGUEDA\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\\u003c\"}"
},
"secondary": {}
},
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "CLEARED",
"job_title": "Accountant",
"kyc_processed_date": "2026-08-12T20:09:47Z",
"kyc_status": "completed",
"kyc_sub_status": "approved",
"last_name": "QAxmy",
"legal_name": "ncmxnc",
"main_income_source": "Salary",
"marital_status": "Single",
"metadata": {
"testing": "aaabbbb"
},
"middle_name": "V",
"mobile": "360351661",
"mobile_country_code": "65",
"mothers_details": {
"first_name": "Jane",
"last_name": "Smith",
"maiden_name": "e t m",
"middle_name": ""
},
"nationality": "Nationality for Germany",
"partner_id": "",
"pending_update": [],
"preferred_name": "Testerqnq",
"provider_account_number": "",
"provider_ref_id": "6a7c61b68597306e52a7e658",
"purpose_of_account_opening": "Cash Deposit",
"require_provider_update": [],
"requirements": {
"eventually_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"immediately_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"pending_verification": {}
},
"residency_country": "Philippines",
"risk_assesment_status": "CLEARED",
"risk_evaluation_date": "2026-08-12T20:09:48Z",
"salutation": "JLXM",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "active",
"status_message": "",
"status_reason_code": "",
"sub_status": "active",
"suffix": "",
"supporting_documents": [
{
"id_issuance_country": "Germany",
"id_issuer_code": "PA",
"id_issuer_name": "passport authority",
"id_issuer_state": "TN",
"id_number": "TesterqnqM41",
"id_sub_type": "abc",
"id_type": "Utility Bill",
"is_expiry_extended": true,
"is_term_unlimited": true,
"metadata": "{'mrx': 'mrzvalue'}"
},
{
"id_date_expiry": "2027-06-28",
"id_date_issued": "2021-06-19",
"id_issuance_country": "Germany",
"id_number": "L02M000CH8",
"id_type": "Other"
}
],
"tin": "ncmxnc",
"title": "Dr",
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"device_id": "SteveOS-High",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Web"
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "individual",
"verification_expiry": "2030-03-14 00:00:00",
"verification_id": {},
"work_country": "Philippines"
},
"verification_results": {
"details": {},
"status": "approved",
"sub_status": "Full KYC Verified",
"sub_status_code": "APPROVED",
"verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18"
}
},
"entity_id": "560b71f5e4904195a0bbd8a37020881b",
"entity_type": "USER",
"event_timestamp": "2026-08-12 20:09:48+0800",
"message_id": "dc6ca6ce-a592-44c5-9cba-10094d5016e5",
"program_code": "{{program_code}}",
"version": "v2",
"webhook_event": "USER.STATUS"
}
USER.STATUS (Rejected) sample webhook payload
ASSOCIATED_PARTIES.PROFILE.STATUS shares the same payload structure as USER.STATUS
{
"entities": {
"user": {
"addresses": {
"billing": {
"city": "ABORLAN_PALAWAN",
"country": "Denmark",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "4107",
"state": "Cavite",
"state_code": "123"
},
"foundation": {},
"identity_verification": {},
"operational": {},
"residential": {
"city": "GABALDON_BITULOK_SAB",
"country": "Germany",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "2200",
"state": "LAUNION",
"state_code": "123"
},
"shipping": {
"city": "ABORLAN_PALAWAN",
"country": "Denmark",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "4107",
"state": "Cavite",
"state_code": "123"
}
},
"agent_id": "",
"alias_name": "ncmxnc",
"annual_income_range": "20000",
"birth": {
"city": "Gen Trias",
"country": "Singapore",
"date": "2000-04-02",
"name": "John Smith",
"postal_code": "1000"
},
"client_ref_id": "9234567891",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2026-08-12T20:04:20Z",
"date_updated": "2026-08-12T20:07:16Z",
"email": "test@matchmove.com",
"employment_details": {
"business_address": {
"city": "ABORLAN_PALAWAN",
"country": "Denmark",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"postal_code": "4107",
"state": "Cavite"
},
"business_purpose": "ACCOUNTING",
"business_trading_name": "abcdefg",
"expected_monthly_revenue": "1000000",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "Manila",
"vat_number": "893678372"
},
"employment_type": "Self Employed",
"ethnicity": "ncmxnc",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {
"first_name": "Steve",
"last_name": "Smith",
"maiden_name": "v c m",
"middle_name": ""
},
"first_name": "Testerqnq",
"gender": "Male",
"http_status_code": 0,
"id": "560b71f5e4904195a0bbd8a37020881b",
"identification": {
"primary": {
"id_date_expiry": "2060-04-24",
"id_date_issued": "2025-06-08",
"id_issuance_country": "Germany",
"id_number": "Testerqnq23132",
"id_type": "Id Card",
"metadata": "{}"
},
"secondary": {}
},
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "PENDING",
"job_title": "Accountant",
"kyc_processed_date": "2026-08-12T20:07:16Z",
"kyc_status": "not_submitted",
"kyc_sub_status": "pending_document_submission",
"last_name": "QAxmy",
"legal_name": "ncmxnc",
"main_income_source": "Salary",
"marital_status": "Single",
"metadata": {
"testing": "aaabbbb"
},
"middle_name": "V",
"mobile": "360351661",
"mobile_country_code": "65",
"mothers_details": {
"first_name": "Jane",
"last_name": "Smith",
"maiden_name": "e t m",
"middle_name": ""
},
"nationality": "Nationality for Germany",
"partner_id": "",
"pending_update": [],
"preferred_name": "Testerqnq",
"provider_account_number": "",
"provider_ref_id": "6a7c61b68597306e52a7e658",
"purpose_of_account_opening": "Cash Deposit",
"require_provider_update": [],
"requirements": {
"eventually_due": {
"required_actions": [],
"required_attributes": [],
"required_documents": []
},
"immediately_due": {
"required_actions": [
"cdd_verification"
],
"required_attributes": [],
"required_documents": []
},
"pending_verification": {
"cdd_verification": {
"verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18"
}
}
},
"residency_country": "Philippines",
"risk_assesment_status": "PENDING",
"risk_evaluation_date": null,
"salutation": "JLXM",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "pending_activation",
"status_message": "",
"status_reason_code": "",
"sub_status": "document_verification_failed",
"suffix": "",
"supporting_documents": [
{
"id_issuance_country": "Germany",
"id_issuer_code": "PA",
"id_issuer_name": "passport authority",
"id_issuer_state": "TN",
"id_number": "TesterqnqM41",
"id_sub_type": "abc",
"id_type": "Utility Bill",
"is_expiry_extended": true,
"is_term_unlimited": true,
"metadata": "{'mrx': 'mrzvalue'}"
},
{
"id_date_expiry": "2030-02-12",
"id_issuance_country": "Spain",
"id_number": "ААА02345678A",
"id_type": "Other"
}
],
"tin": "ncmxnc",
"title": "Dr",
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"device_id": "SteveOS-High",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Web"
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "individual",
"verification_expiry": "2026-09-11 00:00:00",
"verification_id": {},
"work_country": "Philippines"
},
"verification_results": {
"details": {},
"status": "pending",
"sub_status": "",
"sub_status_code": "",
"verification_id": "vfc_d06f5259999540ef8d68c0fd12d43a18"
}
},
"entity_id": "560b71f5e4904195a0bbd8a37020881b",
"entity_type": "USER",
"event_timestamp": "2026-08-12 20:07:18+0800",
"message_id": "11331635-226b-4485-b1a1-55b6f383a611",
"program_code": "{{program_code}}",
"version": "v2",
"webhook_event": "USER.STATUS"
}
5
[Optional] Access individual users' KYC documents
All of the documents submitted by the individual user during eKYC will be accessible for the partner for audit purposes.
List KYC Documents
Call List KYC Documents (GET /users/authentications/documents) to retrieve the list of documents submitted by the user during KYC, along with the download links for each document.
The response of this endpoint will contain details regarding the uploaded file, including but not limited to:
file_type- describes the type or category of the document that was uploaded, e.g.,ID.document_type- describes what document under a certain file type was uploaded, e.g.,selfie.link- the downloadable permalink to the uploaded documentdate.created- the timestamp of the document upload
List KYC Documents request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/authentications/documents' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••''
List KYC Documents response
{
"verification_id": "vfc_487e7b22e4ed4263x576843389373f22",
"status": "completed",
"sub_status": "approved",
"sub_status_code": "APPROVED",
"sub_status_description": "Full KYC Verified",
"documents": [
{
"provider_document_id": "494631728",
"type": "ID",
"document_id": "",
"file_type": "ID",
"document_type": "Primary ID Document",
"kyc_type": "",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/3FAIXULCJ8u2hM62lzOehXWGEYf.jpg",
"id": "3FAIXULCJ8u2hM62lzOefXWDEYf",
"status": "uploaded",
"date": {
"created": "2026-06-15T16:18:06+08:00"
}
},
{
"provider_document_id": "639470662",
"type": "ID",
"document_id": "",
"file_type": "ID",
"document_type": "selfie",
"kyc_type": "",
"link": "https://storage.uat.matchmove-beta.com/api/v1/files/{{program_code}}/kyc/download/3FAIsd5577h8xgrwmqiqotHT1Ra.jpg",
"id": "3FAIXd5577h8x4rwmqiqotHT1Ra",
"status": "uploaded",
"date": {
"created": "2026-06-15T16:18:08+08:00"
}
}
],
"count": 2,
"metadata": {}
}
*To ensure data security, all document URLs provided in the response are time-sensitive and will expire within 5 minutes. Subsequent access beyond this timeframe will require you to generate or refresh the links.
Related Links
On this page
- [SG] Document-based verification