[SG] Authentication-based verification
Explore the steps required to submit information for an authentication-based individual user identity verification. This document provides a clear overview of the specific Know Your Customer (KYC) requirements tied to this verification mode. Use this guide to easily navigate the requirements and complete the authentication-based verification process.
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 do authentication-based verification using SG MyInfo integration.
Prerequisites
- The individual user profile must be created. Refer to the Register customer profile (v2) section for more details.
- The user profile must have identification details such as
identification.primary.id_typeandidentification.primary.id_issuance_countryfields. These will be used to check whether the user is eligible for authentication-based verification.
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
Check if user is eligible for authentication-based verification
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 authentication_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":"authentication_based",
"redirect_url":"www.partner-callback.com",
"redirect_mode": "button",
"redirect_text": "Exit"
}'
Initiate KYC Capture (Individual User) success response - user is eligible
{
"created_date": "2026-09-11T11:22:33+0800",
"id": "{{user_id}}",
"links": [
{
"href": "https://api-sg-sdk.matchmove-beta.com/v2/web/sdk?id=459b1dac9fdf956071daa9bd429c950265894269b7ab067a3f3156b4f6bace75d4565445192c48db9125940f6559957eafa0198c4d7fd3da2538e01878d1eaeb8a4ec2680ad50d9bbab826881a28a41046a8f71a0656d6fd84cf8c03cad4bdd9cf04e53bd0fc0c862940bb5f8495ccbe256ab25d74b1925f913c44c339cc6f095244c807189ab3bfaa61e55de1da2d029abe9ffd352c7721ab755e5908ccf4d60bc0eb5ab519528519ed8f2d2c48463b5aa7506391d635b8e26f739e4e5030c968a69284476608b2833f097b4106a79130fbade896811970bdaa17fd246cf345e5e1b67e0eef8f0f7268f32f025e3b150de020fedb917d02552a178cf2ae8eaa474696c7694670285433175d9dd844de4de81ff951&request_id=c2dtbWRseXQ6Mzg4YWFjZGQ3OTBjNDFjYjkyMGE4MzM1N2U0OWQxNTE6dXNlcg==&user_id=&auth_token=",
"method": "GET",
"rel": "capture.sdk"
}
],
"requirements": null,
"sub_type": "individual",
"type": "users",
"verification_id": "vfc_038db44607174a8182bd0f85201528e5",
"verification_mode": "authentication_based"
}
Initiate KYC Capture (Individual User) failure response - user is not eligible
{
"id": "0c6577dc-58d5-4daa-989a-5668b08d57b7",
"status": "user_eligibility_failed",
"code": 422,
"title": "User Eligibility Failed",
"description": "Requested verification mode is not allowed for the user",
"link": "https://developer.matchmove.com/docs/optimus-prime/docs/Overview/4.%20Handle%20Errors/b.-Error-List.md#user_eligibility_failed",
"timestamp": "16/Jul/2026:08:33:01 +0000 UTC"
}
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 user can authenticate via the trusted third-party platform to grant access to their verified data and complete the KYC submission
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 | 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 | Handle Associated Party (Individual) status changes as outlined in the Business eKYC - KYC and Business User State Transition Updates section. |
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"
}
On this page
- [SG] Authentication-based verification