Update individual profile
Learn how to modify the personal information and contact details associated with an individual user account. Understand the data requirements for maintaining accurate and current user profiles within the system.
The Users V2 API for user onboarding is only supported in a select number of regions that have unique verification processes, customized and more restrictive requirements.
Partners using or assigned to the Users V1 API should not upgrade to the Users V2 API, unless advised otherwise.
Use Cases
- You want to update an existing individual user profile before the user's KYC is approved.
- You want to update an existing individual user profile after the user's KYC has been approved.
Prerequisites
- Before starting to collect individual user information from your customers, refer to the User Protection Guidelines, which all platform consumers and partners must follow and adhere to with regard to securing customer data.
- You will need to collect the user information from the individual customer. This activity must be accomplished before calling the first API in the onboarding workflow. Information can be collected in-app from the partner's mobile or web application.
Individual User data
The data that needs to be collected from the customer can be broken down into these groups:
- API mandatory (minimum) user details — are the vital identity information necessary to create a user in the system.
- User demographic information — includes additional statistics and location details for users.
- Income and other supporting details — include sources of income, employment, and other user details.
API Workflow (v2)
1
[Pre-KYC Profile Update] Update the customer profile in preparation for KYC
In anticipation of performing the Full KYC (Pre-KYC) on your users, the demographic information, income, and other supporting details must be collected and added to the user profile. Failure to provide all the required information will block the KYC submission process.
For the list of all the updateable user fields, please refer to the Update User (V2) API definition.
Update User
Call the Update User (PUT /users) to update the user profile's updateable fields.
Update User request
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic ••••••' \
--data '{
"first_name": "Johnny",
"last_name": "Smith"
}'Update User response
{
"addresses": {
"billing": {
"city": "Cebu City, Cebu",
"country": "Philippines",
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "Region VII",
"postal_code": "6000",
"state": "CEBU"
},
"identity_verification": {},
"residential": {
"city": "Cebu City, Cebu",
"country": "Philippines",
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "Region VII",
"postal_code": "6000",
"state": "CEBU"
},
"shipping": {}
},
"agent_id": "",
"annual_income_range": "100 to 1000",
"birth": {
"city": "Cebu",
"country": "Philippines",
"date": "1990-06-15",
"name": "John Smith",
"postal_code": "6000"
},
"client_ref_id": "1234567891",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2025-08-06T11:36:08Z",
"date_updated": "2025-08-06T11:36:08Z",
"email": "john.smith@matchmove.com",
"employment_details": {
"business_address": {
"city": "PASIG_CITY_NCR",
"country": "PHL",
"line_1": "Ortigas Center",
"line_2": "San Antonio",
"line_3": ".",
"line_4": "NCR",
"postal_code": "4107",
"state": "NCR"
},
"business_purpose": "Financials",
"business_trading_name": "MatchMove Pay Pte Ltd",
"expected_monthly_revenue": "1000000",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "",
"vat_number": "0000000"
},
"employment_type": "EMPLOYED_REGULAR",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {
"first_name": "Juan",
"last_name": "Smith",
"maiden_name": "Juan Johnson",
"middle_name": "Johnson"
},
"first_name": "Johnny",
"gender": "male",
"id": "34f7579b81ff462da64b6fa5e35198fe",
"identification": {
"primary": {
"id_date_expiry": "2025-08-24",
"id_date_issued": "2019-08-24",
"id_issuance_country": "Philippines",
"id_number": "000000",
"id_type": "drivers_id"
},
"secondary": {
"id_date_expiry": "2025-08-24",
"id_date_issued": "2019-08-24",
"id_issuance_country": "Philippines",
"id_number": "000000",
"id_type": "passport"
}
},
"is_email_verified": "0",
"is_mobile_verified": "0",
"is_risk_flagged": "UNKNOWN",
"job_title": "Software Engineer",
"kyc_processed_date": "",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"last_name": "Smith",
"main_income_source": "PAYROLL",
"marital_status": "Married",
"metadata": {},
"middle_name": "Williams",
"mobile": "9999999999",
"mobile_country_code": "63",
"mothers_details": {
"first_name": "Juana",
"last_name": "Smith",
"maiden_name": "Juana Williams",
"middle_name": "Williams"
},
"nationality": "PHL",
"partner_id": "",
"pending_update": [],
"preferred_name": "John Smith",
"provider_account_number": "",
"provider_ref_id": "",
"purpose_of_account_opening": "",
"requirements": {
"eventually_due": {
"required_actions": [],
"required_attributes": []
},
"immediately_due": {
"required_actions": [],
"required_attributes": []
},
"pending_verification": {}
},
"residency_country": "Philippines",
"risk_assesment_status": "UNKNOWN",
"salutation": "JLXM",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "pending_verification",
"sub_status": "",
"title": "Mr",
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"device_id": "",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Curl"
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "customer",
"work_country": "Philippines"
}2
[Post-KYC Profile Update] Update the allowed fields in a KYC-approved profile
Depending on the program region, information updates to the user profile may have certain restrictions.
During this time, the customer profile and the KYC documents have already been verified and approved. Any update to the user profile may an effect on the issued financial assets to the user.
Therefore, updates to user information fields will require additional verification. While updates to the critical fields may be blocked entirely.
Update User critical fields:
first_namemiddle_name(optional)last_namepreferred_name
Updates to the following fields are not allowed when:
- The user is already KYC
approved - The user status is already
active - The user has already been issued an account/wallet.
Special fields requiring additional re-verification when updated, after the customer's KYC has been approved:
- Mobile number
- Email address
- Residential address
- Billing address
For the list of other updateable user fields, please refer to the Update User (V2) API definition.
Update User
Call the Update User (PUT /users) to update the user profile's updateable fields.
Update User request (email updated)
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/{{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"email": "johnny.smith@matchmove.com"
}
}'Update User response (email updated)
{
"addresses": {
"billing": {
"city": "Cebu City, Cebu",
"country": "Philippines",
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "Region VII",
"postal_code": "6000",
"state": "CEBU"
},
"identity_verification": {},
"residential": {
"city": "Cebu City, Cebu",
"country": "Philippines",
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "Region VII",
"postal_code": "6000",
"state": "CEBU"
},
"shipping": {}
},
"agent_id": "",
"annual_income_range": "100 to 1000",
"birth": {
"city": "Cebu",
"country": "Philippines",
"date": "1990-06-15",
"name": "John Smith",
"postal_code": "6000"
},
"client_ref_id": "1234567891",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2025-08-06T11:36:08Z",
"date_updated": "2025-08-06T11:36:08Z",
"email": "john.smith@matchmove.com",
"employment_details": {
"business_address": {
"city": "PASIG_CITY_NCR",
"country": "PHL",
"line_1": "Ortigas Center",
"line_2": "San Antonio",
"line_3": ".",
"line_4": "NCR",
"postal_code": "4107",
"state": "NCR"
},
"business_purpose": "Financials",
"business_trading_name": "MatchMove Pay Pte Ltd",
"expected_monthly_revenue": "1000000",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "",
"vat_number": "0000000"
},
"employment_type": "EMPLOYED_REGULAR",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {
"first_name": "Juan",
"last_name": "Smith",
"maiden_name": "Juan Johnson",
"middle_name": "Johnson"
},
"first_name": "Johnny",
"gender": "male",
"id": "34f7579b81ff462da64b6fa5e35198fe",
"identification": {
"primary": {
"id_date_expiry": "2025-08-24",
"id_date_issued": "2019-08-24",
"id_issuance_country": "Philippines",
"id_number": "000000",
"id_type": "drivers_id"
},
"secondary": {
"id_date_expiry": "2025-08-24",
"id_date_issued": "2019-08-24",
"id_issuance_country": "Philippines",
"id_number": "000000",
"id_type": "passport"
}
},
"is_email_verified": "0",
"is_mobile_verified": "0",
"is_risk_flagged": "UNKNOWN",
"job_title": "Software Engineer",
"kyc_processed_date": "",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"last_name": "Smith",
"main_income_source": "PAYROLL",
"marital_status": "Married",
"metadata": {},
"middle_name": "Williams",
"mobile": "9999999999",
"mobile_country_code": "63",
"mothers_details": {
"first_name": "Juana",
"last_name": "Smith",
"maiden_name": "Juana Williams",
"middle_name": "Williams"
},
"nationality": "PHL",
"partner_id": "",
"pending_update": [],
"preferred_name": "John Smith",
"provider_account_number": "",
"provider_ref_id": "",
"purpose_of_account_opening": "",
"requirements": {
"eventually_due": {
"required_actions": [],
"required_attributes": []
},
"immediately_due": {
"required_actions": [],
"required_attributes": []
},
"pending_verification": {}
},
"residency_country": "Philippines",
"risk_assesment_status": "UNKNOWN",
"salutation": "JLXM",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "pending_verification",
"sub_status": "",
"title": "Mr",
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"device_id": "",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Curl"
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "customer",
"work_country": "Philippines"
"requirements" : {
"eventually_due": {
"required_attributes" : [],
"required_actions": []
},
"immediately_due": {
"required_attributes": [ ],
"required_actions": [ "email_verification" ]
},"
pending_verification": {
"email": {
"created_at": "2024-06-25 15:20:39",
"expired_at": "2024-07-09 15:20:39",
"verification_data": {
"email": "johnny.smith@matchmove.com"
},
"verification_id" : "4757b9126e17491f9a0e22e39775569d"
}
}
}
}
}jsonOnce Update User is executed on the special fields, its response will have an additional payload requirements detailing whether additional actions are required for the profile update.
These requirements will need to be satisfied before the updated changes get committed and reflected in the user profile.
Update User response on Post-KYC update (excepts)
"requirements": { "eventually_due": { "required_attributes" : [], "required_actions": [] }, "immediately_due": { "required_attributes": [ ], "required_actions": [ "email_verification" ] }," pending_verification": { "email": { "created_at": "2024-06-25 15:20:39", "expired_at": "2024-07-09 15:20:39", "verification_data": { "email": "johnny.smith@matchmove.com" }, "verification_id" : "4757b9126e17491f9a0e22e39775569d"} } } }
The table below outlines the various properties possible for the requirements object and the corresponding
| Fields that are required to be processed/collected immediately under |
|
|
| Fields that need to be collected but are not critical for the user process under | ||
| Fields that might become required depending on the results of verification or review. It’s an empty object unless an asynchronous verification is pending under |
|
|
| Fields that will get updated to the system only after the respective external dependency (from the license provider or any third-party provider) or verification requirements. |
|
Platform-level mobile and email verification
Currently, the platform mechanism for mobile/email verification is only available for the initial user profile creation. Verification of mobile/email during the Post-KYC update will need to be managed by the partner (self-verification). Self-verification entails the partner performing their own verification process on the updated fields that require re-verification.
The partner will have to do a self-verification activity, where they can verify the mobile or email using their own capabilities and services.
Once the self-verification is completed, the partner is required to pass some metadata of their completed verification. These metadata will be used for the purposes of audit.
Every updated field requiring verification will have an associated verification ID in the requirements block in the user payload.
Self-verify OTP
Call the Self-verify OTP (POST /users/verify) to pass the self-verification metadata to the platform. Passing the following:
Verification ID | verification_id | Verification ID associated with the updated field. This ID can be located in the requirements block in the Get User payload. |
Partner verification metadata | id | Verification ID (verification_id) associated with the field being verified. |
mode | Defaulted to | |
document_type | Allowed values:
| |
document_id | Partner-Internal verification document identifier |
Self-verify request
curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify' \
--header 'content-type: application/json' \
--header 'Authorization: ••••••' \
--header 'X-Auth-User-ID: {{user_id}}' \
--data-raw '{
"id": "4757b9126e17491f9a0e22e39775569d",
"mode": "MANUAL",
"document_type": "PROOF_OF_EMAIL_OWNERSHIP",
"document_id": "ba02d43c-3cc2-49b7-96c2-ed0861e55a83",
"authentication_data": {
"device_id": "id0001",
"ip": "127.0.0.1",
"os": "SteveOS-High",
"user_agent": ""
},
"date": "2024-05-24"
}'Self-verify response
{
"action": "email_verification",
"user_id": "{{user_id}}",
"id": "9085376ed64e407791334571e45fc8ce",
"mode": "MANUAL",
"verification_data": {
"email": "johnny.smith@matchmove.com"
},
"authentication_data": {
"device_id": "id0001",
"ip": "127.0.0.1",
"os": "SteveOS-High"
},
"status": "success"
}3
[Post-KYC Profile Update] Monitor if the status of the request for user profile update
Once the fields requiring re-verification have been self-verified by the partner, these fields will be sent to the licensed provider or the bank partner for approval of the change.
Once approved, the changes requested will be committed, and the user profile will be updated accordingly.
If the partner wants to be notified when a user profile update request is completed, they must subscribe to the “User Details” webhook category and events.
Go to the Leverage Webhooks section to learn more about setting up the webhooks.
Sample webhook payload
"event_data\":{\"entities\":{\"user\":{\"addresses\":{\"billing\":{\"city\":\"ADAMS_ILOCOS_NORTE\",\"country\":\"PHL\",\"line_1\":\"119 Pine St\",\"line_2\":\"Maryland Subd\",\"line_3\":\"Phase\",\"line_4\":\"REGION_03\",\"postal_code\":\"400\",\"state\":\"ANTIQUE\"},\"identity_verification\":{},\"residential\":{\"city\":\"ADAMS_ILOCOS_NORTE\",\"country\":\"PHL\",\"line_1\":\"119 Pine St\",\"line_2\":\"Maryland Subd\",\"line_3\":\"Phase\",\"line_4\":\"REGION_03\",\"postal_code\":\"400\",\"state\":\"ANTIQUE\"},\"shipping\":{}},\"agent_id\":\"\",\"annual_income_range\":\"\",\"birth\":{\"date\":\"1990-03-13\"},\"client_ref_id\":\"\",\"customer_id\":\"\",\"data_terms_signed_at\":\"\",\"date_created\":\"2025-10-15T21:19:05Z\",\"date_updated\":\"2026-01-27T16:35:43Z\",\"email\":\"john.smith@matchmove.com\",\"employment_details\":{\"business_address\":{\"city\":\"ABORLAN_PALAWAN\",\"country\":\"PHL\",\"line_1\":\"Line1 street 101\",\"line_2\":\"Line2 street 101\",\"line_3\":\"Phase\",\"line_4\":\"REGION_01\",\"postal_code\":\"400\",\"state\":\"ABRA\"},\"business_purpose\":\"\",\"business_trading_name\":\"Employer Name\",\"expected_monthly_revenue\":\"\",\"industry\":\"\",\"industry_key\":\"\",\"own_economic_interest_signed_at\":\"\",\"vat_number\":\"\"},\"employment_type\":\"COMMISSION_BASED_AGENT\",\"fatca_crs_confirmed_at\":\"0001-01-01T00:00:00Z\",\"fatca_relevant\":false,\"father_details\":{},\"first_name\":\"John\",\"gender\":\"MALE\",\"id\":\"25ce05638628453ab1c0d2ea3e7562cc\",\"identification\":{\"primary\":{\"id_date_expiry\":\"2027-10-13\",\"id_date_issued\":\"2025-10-13\",\"id_issuance_country\":\"PHL\",\"id_number\":\"6009005384144\",\"id_type\":\"UMID\"},\"secondary\":{}},\"is_email_verified\":\"1\",\"is_mobile_verified\":\"1\",\"is_risk_flagged\":\"UNKNOWN\",\"job_title\":\"\",\"kyc_processed_date\":\"2025-10-27T02:23:05Z\",\"kyc_status\":\"completed\",\"kyc_sub_status\":\"approved\",\"last_name\":\"Smith\",\"main_income_source\":\"COBRANDING_PARTNER\",\"marital_status\":\"MARRIED\",\"metadata\":null,\"middle_name\":\"Williams\",\"mobile\":\"9299534289\",\"mobile_country_code\":\"63\",\"mothers_details\":{\"maiden_name\":\"Juana Steven\"},\"nationality\":\"PHL\",\"partner_id\":\"\",\"pending_update\":[],\"preferred_name\":\"John Smith\",\"provider_account_number\":\"930100139810\",\"provider_ref_id\":\"HMAP251015000043631\",\"purpose_of_account_opening\":\"\",\"requirements\":{\"eventually_due\":{\"required_actions\":[],\"required_attributes\":[]},\"immediately_due\":{\"required_actions\":[],\"required_attributes\":[]},\"pending_verification\":{}},\"residency_country\":\"\",\"risk_assesment_status\":\"UNKNOWN\",\"salutation\":\"\",\"self_declared_as_pep\":false,\"socioprofessional_category\":\"\",\"status\":\"active\",\"sub_status\":\"active\",\"title\":\"MADAM\",\"tos_acceptance\":{\"date\":\"0001-01-01T00:00:00Z\",\"device_id\":\"\",\"ip\":\"\",\"service_agreement\":\"\",\"user_agent\":\"\"},\"transaction_status\":\"\",\"transaction_sub_status\":\"\",\"type\":\"customer\",\"work_country\":\"\"}},\"entity_id\":\"25ce05638628453ab1c0d2ea3e7562cc\",\"entity_type\":\"USER\",\"event_timestamp\":\"2026-01-27T16:35:47Z\",\"message_id\":\"9d0c227a-9fef-45d2-b314-e91670967b40\",\"program_code\":\"{{product_code}}\",\"version\":\"v2\",\"webhook_event\":\"USER.INDIVIDUAL.INFORMATION_UPDATE.STATUS\"},\"event_name\":\"USER.INDIVIDUAL.INFORMATION_UPDATE.STATUS\",\"max_retry_age\":0,\"max_retry_attempts\":0,\"product_code\":\"{{product_code}}\",\"retry_attempt\":19,\"service_name\":\"customer\",\"trace_id\":\"25ce05638628453ab1c0d2ga3e7562cc_b6cc8c5e578a4b20a0e192e07de2c3ab\",\"webhook_id\":\"5199526d-fd73-4070-8cd7-191424d81317\"}"Related Links
On this page
- Update individual profile