Register individual profile
Learn how to create an individual user profile, the foundational step for onboarding a new user. Understand this initial process of registering an individual on the platform before proceeding with identity verification.
The Users V2 API for user onboarding is only supported in a select number of regions that have unique verification processes 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 onboard an individual user who is a natural person, not a business or corporate entity.
- You want to onboard an individual user who will use an account for personal purposes.
- You want to onboard an individual user who is a single employee, contractor, or affiliate of a corporate entity.
- When business users are enabled, and you want to onboard an individual user and associate him with a business entity.
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
Create an individual user profile in the program
During your initial interaction with the customer, you may want to reduce the initial set of information you ask them. This can reduce the friction of onboarding and increase the turnover rate of your sign-ups.
There are multiple onboarding options available for profile creation:
- Email address - a user profile can be created by providing just the email address first
- Mobile number - a user profile can be created by providing just the mobile number first
- Complete information - a user profile can be created by supplying the complete required user information
Create User
You can call the Create User (POST /users) to create a user by passing the required information.
Individual user registration
Create User - Providing minimum required information
Create User - Providing minimum required information
Minimum required user information
Collecting minimum information from the user during the initial contact will reduce onboarding friction and increase user acquisition. By segmenting the user onboarding, we can also reduce the form fields being built on the frontend to collect user information. Instead, we can then just allow the user to provide all the required information and documents during the eKYC information collection screens. For individuals, the minimum required user information is the following:
preferred_namefirst_namelast_nameemailmobile_country_codemobile
Create User request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
"preferred_name": "John Smith",
"email": "jsm@matchmove.com",
"mobile_country_code": "65",
"mobile": "91919199",
"first_name": "John",
"last_name": "Smith"
}'Create User response
JSON
{
"id": "c90e71d1572e437e80c0aec126e1874a",
"type": "individual",
"client_ref_id": "",
"provider_ref_id": "",
"provider_account_number": "",
"salutation": "",
"suffix": "",
"title": "",
"first_name": "John",
"middle_name": "",
"last_name": "Smith",
"preferred_name": "John Smith",
"email": "jsm@matchmove.com",
"mobile_country_code": "65",
"mobile": "91919199",
"gender": "",
"marital_status": "",
"identification": {
"primary": {},
"secondary": {}
},
"birth": {},
"nationality": "",
"mothers_details": {},
"father_details": {},
"addresses": {
"residential": {},
"billing": {},
"shipping": {},
"identity_verification": {},
"foundation": {},
"operational": {}
},
"employment_type": "",
"job_title": "",
"employment_details": {
"business_trading_name": "",
"business_purpose": "",
"industry": "",
"industry_key": "",
"own_economic_interest_signed_at": "",
"expected_monthly_revenue": "",
"vat_number": "",
"business_address": {}
},
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"data_terms_signed_at": "",
"annual_income_range": "",
"main_income_source": "",
"purpose_of_account_opening": "",
"socioprofessional_category": "",
"work_country": "",
"residency_country": "",
"self_declared_as_pep": false,
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"ip": "",
"service_agreement": "",
"user_agent": "",
"device_id": ""
},
"metadata": null,
"agent_id": "",
"partner_id": "",
"customer_id": "",
"status": "pending_activation",
"sub_status": "document_submission_required",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"transaction_status": "",
"transaction_sub_status": "",
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "UNKNOWN",
"kyc_processed_date": "",
"date_created": "2026-05-05T14:09:14Z",
"date_updated": "0001-01-01T00:00:00Z",
"pending_update": [],
"verification_id": {},
"require_provider_update": [],
"http_status_code": 0,
"requirements": {
"immediately_due": {
"required_attributes": [],
"required_actions": []
},
"eventually_due": {
"required_attributes": [],
"required_actions": []
},
"pending_verification": {}
},
"risk_assesment_status": "UNKNOWN",
"status_reason_code": "",
"status_message": ""
}Create User - Providing complete user infomation
Create User - Providing complete user infomation
Region-specific Onboarding
The example below displays the exhaustive set of user information fields that can be passed through the Create User endpoint.
However, since this endpoint is utilized for multiple regions with different regulatory requirements, usage per region will differ.
Partners are encouraged to refer to the Region-specific Onboarding section to see the list of information required for their program region.
Only the listed region-specific user information is required to be collected from the users and submitted for user registration.
Create User request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
"client_ref_id": "1234567891",
"type": "individual",
"salutation": "JLXM",
"title": "Mr",
"first_name": "John",
"middle_name": "William",
"last_name": "Smith",
"preferred_name": "John Smith",
"gender": "male",
"mobile_country_code": "63",
"mobile": "9999999999",
"email": "john.smith@matchmove.com",
"marital_status": "Married",
"identification": {
"primary": {
"id_number": "000000",
"id_type": "passport",
"id_date_added": "2019-08-24",
"id_date_issued": "2019-08-24",
"id_date_expiry": "2029-08-24",
"id_issuance_country": "PHL"
},
"secondary": {
"id_number": "000000",
"id_type": "drivers_id",
"id_date_added": "2019-08-24",
"id_date_issued": "2019-08-24",
"id_date_expiry": "2029-08-24",
"id_issuance_country": "PHL"
}
},
"birth": {
"name": "John William Smith",
"date": "1990-06-15"
},
"nationality": "Filipino",
"mothers_details": {
"first_name": "Juana",
"middle_name": "Williams",
"last_name": "Smith",
"maiden_name": "Juana Williams"
},
"fathers_details": {
"first_name": "Juan",
"middle_name": "Johnson",
"last_name": "Smith",
"maiden_name": "Juan Johnson"
},
"addresses": {
"residential": {
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "REGION_07",
"postal_code": "6000",
"city": "CEBU_CITY_CEBU",
"country": "PHL",
"state": "CEBU"
},
"billing": {
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "REGION_07",
"postal_code": "6000",
"city": "CEBU_CITY_CEBU",
"country": "PHL",
"state": "CEBU"
}
},
"employment_details": {
"business_trading_name": "MatchMove Pay Pte Ltd",
"business_purpose": "Financials",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "",
"expected_monthly_revenue": "1000000",
"vat_number": "0000000",
"business_address": {
"line_1": "Ortigas Center",
"line_2": "San Antonio",
"line_3": ".",
"line_4": "NCR",
"postal_code": "4107",
"city": "PASIG_CITY_NCR",
"country": "PHL",
"state": "NCR"
}
},
"fatca_crs_confirmed_at": "2023-09-18T14:15:22Z",
"fatca_relevant": true,
"main_income_source": "SALARY",
"socioprofessional_category": "",
"purpose_of_account_opening": "",
"work_country": "Philippines",
"residency_country": "PHL",
"self_declared_as_pep": true,
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Curl",
"device_id": "SteveOS-High"
},
"provider_ref_id": "",
"provider_account_number": "",
"posting_status": "",
"data_terms_signed_at": "",
"metadata": {},
"created_by": "bot@matchmove.com"
}'Create User response
JSON
{
"id": "672a00188e78487fab80ff5189c79cee",
"type": "individual",
"client_ref_id": "1234567891",
"provider_ref_id": "",
"provider_account_number": "",
"salutation": "JLXM",
"suffix": "",
"title": "Mr",
"first_name": "John",
"middle_name": "William",
"last_name": "Smith",
"preferred_name": "John Smith",
"email": "john.smith@matchmove.com",
"mobile_country_code": "63",
"mobile": "9999999999",
"gender": "Male",
"marital_status": "Married",
"identification": {
"primary": {
"id_number": "000000",
"id_type": "Passport",
"id_date_issued": "2019-08-24",
"id_date_expiry": "2029-08-24",
"id_issuance_country": "Philippines"
},
"secondary": {
"id_number": "000000",
"id_type": "Driver's license",
"id_date_issued": "2019-08-24",
"id_date_expiry": "2029-08-24",
"id_issuance_country": "Philippines"
}
},
"birth": {
"name": "John William Smith",
"date": "1990-06-15"
},
"nationality": "Nationality for Philippines",
"mothers_details": {
"first_name": "Juana",
"middle_name": "Williams",
"last_name": "Smith",
"maiden_name": "Juana Williams"
},
"father_details": {
"first_name": "Juan",
"middle_name": "Johnson",
"last_name": "Smith",
"maiden_name": "Juan Johnson"
},
"addresses": {
"residential": {
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "REGION_07",
"city": "CEBU_CITY_CEBU",
"state": "CEBU",
"postal_code": "6000",
"country": "Philippines"
},
"billing": {
"line_1": "Resi",
"line_2": "Somerset",
"line_3": "Phase",
"line_4": "REGION_07",
"city": "CEBU_CITY_CEBU",
"state": "CEBU",
"postal_code": "6000",
"country": "Philippines"
},
"shipping": {},
"identity_verification": {},
"foundation": {},
"operational": {}
},
"employment_type": "",
"job_title": "",
"employment_details": {
"business_trading_name": "MatchMove Pay Pte Ltd",
"business_purpose": "Financials",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "",
"expected_monthly_revenue": "1000000",
"vat_number": "0000000",
"business_address": {
"line_1": "Ortigas Center",
"line_2": "San Antonio",
"line_3": ".",
"line_4": "NCR",
"postal_code": "4107",
"city": "PASIG_CITY_NCR",
"country": "Philippines",
"state": "NCR"
}
},
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"data_terms_signed_at": "",
"annual_income_range": "",
"main_income_source": "Salary",
"purpose_of_account_opening": "",
"socioprofessional_category": "",
"work_country": "Philippines",
"residency_country": "Philippines",
"self_declared_as_pep": false,
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Curl",
"device_id": "SteveOS-High"
},
"metadata": null,
"agent_id": "",
"partner_id": "",
"customer_id": "",
"status": "pending_activation",
"sub_status": "document_submission_required",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"transaction_status": "",
"transaction_sub_status": "",
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "UNKNOWN",
"kyc_processed_date": "",
"date_created": "2026-04-06T12:13:10Z",
"date_updated": "0001-01-01T00:00:00Z",
"pending_update": [],
"verification_id": {},
"require_provider_update": [],
"http_status_code": 0,
"requirements": {
"immediately_due": {
"required_attributes": [],
"required_actions": []
},
"eventually_due": {
"required_attributes": [],
"required_actions": []
},
"pending_verification": {}
},
"risk_assesment_status": "UNKNOWN",
"status_reason_code": "",
"status_message": ""
}Individual user registration (PH-specific)
[PH] Create User - Providing email only initially
[PH] Create User - Providing email only initially
*This method of creating users is only available for the PH region.
Create User request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
"type": "customer",
"email": "john.smith@matchmove.com",
"preferred_name": "John Smith"
}'Create User response
JSON
{
"addresses": {
"billing": {},
"identity_verification": {},
"residential": {},
"shipping": {}
},
"agent_id": "",
"annual_income_range": "",
"birth": {},
"client_ref_id": "",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2025-08-06T11:32:11Z",
"date_updated": "2025-08-06T11:32:11Z",
"email": "john.smith@matchmove.com",
"employment_details": {
"business_address": {},
"business_purpose": "",
"business_trading_name": "",
"expected_monthly_revenue": "",
"industry": "",
"industry_key": "",
"own_economic_interest_signed_at": "",
"vat_number": ""
},
"employment_type": "",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {},
"first_name": "",
"gender": "",
"id": "18a2882d4ed04e35804e9d64138f6fe2", "business_id": "{{parent_business_id}}",
"identification": {
"primary": {},
"secondary": {}
},
"is_email_verified": "0",
"is_mobile_verified": "0",
"is_risk_flagged": "UNKNOWN",
"job_title": "",
"kyc_processed_date": "",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"last_name": "",
"main_income_source": "",
"marital_status": "",
"metadata": null,
"middle_name": "",
"mobile": "",
"mobile_country_code": "",
"mothers_details": {},
"nationality": "",
"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": "",
"risk_assesment_status": "UNKNOWN",
"salutation": "",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "pending_verification",
"sub_status": "",
"title": "",
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"device_id": "",
"ip": "",
"service_agreement": "",
"user_agent": ""
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "customer",
"work_country": ""
}[PH] Create User - Providing mobile only initially
[PH] Create User - Providing mobile only initially
*This method of creating users is only available for the PH region.
Create User request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"type": "customer",
"mobile_country_code": "63",
"mobile": "9999999999",
"preferred_name": "John Smith"
}'Create User response
JSON
{
"addresses": {
"billing": {},
"identity_verification": {},
"residential": {},
"shipping": {}
},
"agent_id": "",
"annual_income_range": "",
"birth": {},
"client_ref_id": "",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2025-08-06T11:33:16Z",
"date_updated": "2025-08-06T11:33:16Z",
"email": "",
"employment_details": {
"business_address": {},
"business_purpose": "",
"business_trading_name": "",
"expected_monthly_revenue": "",
"industry": "",
"industry_key": "",
"own_economic_interest_signed_at": "",
"vat_number": ""
},
"employment_type": "",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {},
"first_name": "",
"gender": "",
"id": "daf9f114501c4652b3bb0daed1ff2998",
"identification": {
"primary": {},
"secondary": {}
},
"is_email_verified": "0",
"is_mobile_verified": "0",
"is_risk_flagged": "UNKNOWN",
"job_title": "",
"kyc_processed_date": "",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"last_name": "",
"main_income_source": "",
"marital_status": "",
"metadata": null,
"middle_name": "",
"mobile": "9999999999",
"mobile_country_code": "63",
"mothers_details": {},
"nationality": "",
"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": "",
"risk_assesment_status": "UNKNOWN",
"salutation": "",
"self_declared_as_pep": false,
"socioprofessional_category": "",
"status": "pending_verification",
"sub_status": "",
"title": "",
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"device_id": "",
"ip": "",
"service_agreement": "",
"user_agent": ""
},
"transaction_status": "",
"transaction_sub_status": "",
"type": "customer",
"work_country": ""
}[PH] Create User - Providing complete user information
[PH] Create User - Providing complete user information
Create User request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
"client_ref_id": "9234567891",
"provider_action_id": "test123",
"preferred_name": "John Smith",
"salutation": "JLXM",
"title": "dr",
"first_name": "John",
"legal_name": "John Smith",
"alias_name": "John Smith",
"tin": "ncmxnc",
"ethnicity": "ncmxnc",
"middle_name": "V",
"last_name": "Smith",
"maiden_name": "jkjdksajd",
"gender": "MALE",
"marital_status": "SINGLE",
"email": "iuqie41cu489551@matchmove.com",
"mobile_country_code": "63",
"mobile": "1194651219",
"provider_data": {
"first_name": "John",
"sirst_name_en": "Smith"
},
"supporting_documents": [
{
"id_number": "M41487196",
"id_type": "ARBITRARY_DOC",
"id_issuance_country": "DNK",
"id_sub_type": "abc",
"id_issuer_name": "passport authority",
"id_issuer_code": "PA",
"id_issuer_state": "TN",
"is_term_unlimited": false,
"is_expiry_extended": false
}
],
"identification": {
"primary": {
"id_number": "M24571148",
"id_type": "passport",
"id_date_added": "2019-08-24",
"id_date_issued": "2025-06-08",
"id_date_expiry": "2028-08-24",
"id_issuance_country": "DNK"
},
"secondary": {
"id_number": "g11516434",
"id_type": "DRIVERS_ID",
"id_date_added": "2019-08-24",
"id_date_issued": "2025-06-08",
"id_date_expiry": "2028-08-24",
"id_issuance_country": "DNK"
}
},
"birth": {
"name": "L",
"date": "2000-04-02",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"city": "ABORLAN_PALAWAN",
"country": "PHL",
"state": "Cavite",
"postal_code": "4107"
},
"nationality": "PHL",
"mothers_details": {
"first_name": "Est",
"middle_name": "Tori",
"last_name": "Mir",
"maiden_name": "e t m"
},
"fathers_details": {
"first_name": "Vir",
"middle_name": "Cab",
"last_name": "Mir",
"maiden_name": "v c m"
},
"addresses": {
"residential": {
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"city": "GABALDON_BITULOK_SAB",
"state": "LAUNION",
"state_code": "123",
"country": "DNK",
"postal_code": "2200"
},
"billing": {
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"city": "ABUCAY_BATAAN",
"state": "Cavite",
"country": "DNK",
"postal_code": "4107"
},
"shipping": {
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"city": "ABORLAN_PALAWAN",
"country": "DNK",
"state": "Cavite",
"postal_code": "4107"
}
},
"employment_type": "OFW",
"job_title": "ACCOUNTANT",
"employment_details": {
"business_purpose": "ACCOUNTING",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "Manila",
"expected_monthly_revenue": "1000000",
"vat_number": "893678372",
"business_address": {
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"city": "ABUCAY_BATAAN",
"country": "DNK",
"state": "Cavite",
"postal_code": "4107"
}
},
"fatca_crs_confirmed_at": "2019-08-24T14:15:22Z",
"fatca_relevant": true,
"annual_income_range": "20000",
"main_income_source": "OFW",
"socioprofessional_category": "string",
"purpose_of_account_opening": "CASH_DEPOSIT",
"work_country": "Philippines",
"residency_country": "Philippines",
"self_declared_as_pep": true,
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Curl",
"device_id": "SteveOS-High"
},
"provider_ref_id": "",
"provider_account_number": "",
"posting_status": "ok",
"data_terms_signed_at": "2022-06-15 00:00:00",
"metadata": {
"testing": "aaabbbb"
},
"created_by": "bot@matchmove.com",
"suffix": "Jr",
"type": "customer"
}'Create User response
JSON
{
"addresses": {
"billing": {
"city": "Abucay, Bataan",
"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"
},
"identity_verification": {},
"residential": {
"city": "Gabaldon (Bitulok & ",
"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": "2200",
"state": "LA UNION",
"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"
}
},
"agent_id": "",
"alias_name": "John Smith",
"annual_income_range": "20000",
"birth": {
"city": "ABORLAN_PALAWAN",
"country": "PHL",
"date": "2000-04-02",
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"name": "John Smith",
"postal_code": "4107",
"state": "CAVITE"
},
"client_ref_id": "9234567891",
"customer_id": "",
"data_terms_signed_at": "",
"date_created": "2026-03-26T21:01:35Z",
"date_updated": "2026-03-26T21:01:35Z",
"email": "iuqie41cu489551@matchmove.com",
"employment_details": {
"business_address": {
"city": "ABUCAY_BATAAN",
"country": "DNK",
"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": "",
"expected_monthly_revenue": "1000000",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "Manila",
"vat_number": "893678372"
},
"employment_type": "OFW",
"ethnicity": "ncmxnc",
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"father_details": {
"first_name": "William",
"last_name": "Smith",
"maiden_name": "v c m",
"middle_name": "Cab"
},
"first_name": "John",
"gender": "MALE",
"id": "02952fb181024e50b0fac33d9b0e1ac6",
"identification": {
"primary": {
"id_date_expiry": "2028-08-24",
"id_date_issued": "2025-06-08",
"id_issuance_country": "Denmark",
"id_number": "M24571148",
"id_type": "passport"
},
"secondary": {
"id_date_expiry": "2028-08-24",
"id_date_issued": "2025-06-08",
"id_issuance_country": "Denmark",
"id_number": "g11516434",
"id_type": "DRIVERS_ID"
}
},
"is_email_verified": "0",
"is_mobile_verified": "0",
"is_risk_flagged": "UNKNOWN",
"job_title": "ACCOUNTANT",
"kyc_processed_date": "",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"last_name": "Smith",
"legal_name": "John Smith",
"main_income_source": "OFW",
"marital_status": "SINGLE",
"metadata": null,
"middle_name": "V",
"mobile": "1194651219",
"mobile_country_code": "63",
"mothers_details": {
"first_name": "Jane",
"last_name": "Smith",
"maiden_name": "e t m",
"middle_name": "Tori"
},
"nationality": "PHL",
"partner_id": "",
"pending_update": [],
"preferred_name": "iuiwueiwe",
"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",
"status_message": "",
"status_reason_code": "",
"sub_status": "",
"suffix": "Jr",
"supporting_documents": [
{
"id_issuance_country": "DNK",
"id_issuer_code": "PA",
"id_issuer_name": "passport authority",
"id_issuer_state": "TN",
"id_number": "M41487196",
"id_sub_type": "abc",
"id_type": "ARBITRARY_DOC"
}
],
"tin": "ncmxnc",
"title": "dr",
"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"
}Business Hierarchical Structure
When business user is enabled in your program, there will be an alternative way to create individual users who need to be associated with a business user entity.
Businesses often organize themselves into layers, where smaller branches or subsidiaries are distinct entities but still belong to the main parent company. Individual employees, on the other hand, are organized directly under their departments or employers. Financial flows follow this same path, where the parent company allocates capital downward for operations, and the revenue generated by these employees flows back up through their branch to the main entity.
MatchMove Banking API is designed to cater to various business structure nuances. You should be able to create parent-child relationships and maintain hierarchical structures with individual and business entities. e.g.,
- Business A (Parent) is associated to Business B (Child)
- Business A (Parent) is associated to Individual User A (Child)
Create a (Sub-business) Individual User
You can call the Create (Sub-business) Individual User (POST /businesses/{{parent_business_id}}/users) passing the business ID of the parent business user to create a child individual user.
Note: This API requires that business users be enabled in your program.
(Sub-business) Individual definition
Create (Sub-business) Individual User - Providing minimum required information
Create (Sub-business) Individual User - Providing minimum required information
Minimum required sub-business information - Individual
Collecting minimum user information from the user during the initial contact will reduce onboarding friction and increase user acquisition. By segmenting the user onboarding, we can also reduce the form fields being built on the frontend to collect user information. Instead, we can then just allow the user to provide all the required information and documents during the eKYC information collection screens. For individuals, the minimum required user information is the following:
preferred_namefirst_namelast_nameemailmobile_country_codemobile
Create (Sub-business) Individual User request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/{{business_parent_id}}/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
"preferred_name": "Junior Smith",
"email": "jrsmith@matchmove.com",
"mobile_country_code": "65",
"mobile": "91929891",
"first_name": "Junior",
"last_name": "Smith"
}'Create (Sub-business) Individual User response
JSON
{
"id": "98b05cf787a34efebeacb2785f4bfc3c",
"type": "individual",
"client_ref_id": "",
"provider_ref_id": "",
"provider_account_number": "",
"salutation": "",
"suffix": "",
"title": "",
"first_name": "Junior",
"middle_name": "",
"last_name": "Smith",
"preferred_name": "Junior Smith",
"email": "jrsmith@matchmove.com",
"mobile_country_code": "65",
"mobile": "91929891",
"gender": "",
"marital_status": "",
"identification": {
"primary": {},
"secondary": {}
},
"birth": {},
"nationality": "",
"mothers_details": {},
"father_details": {},
"addresses": {
"residential": {},
"billing": {},
"shipping": {},
"identity_verification": {},
"foundation": {},
"operational": {}
},
"employment_type": "",
"job_title": "",
"employment_details": {
"business_trading_name": "",
"business_purpose": "",
"industry": "",
"industry_key": "",
"own_economic_interest_signed_at": "",
"expected_monthly_revenue": "",
"vat_number": "",
"business_address": {}
},
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"data_terms_signed_at": "",
"annual_income_range": "",
"main_income_source": "",
"purpose_of_account_opening": "",
"socioprofessional_category": "",
"work_country": "",
"residency_country": "",
"self_declared_as_pep": false,
"tos_acceptance": {
"date": "0001-01-01T00:00:00Z",
"ip": "",
"service_agreement": "",
"user_agent": "",
"device_id": ""
},
"metadata": null,
"agent_id": "",
"partner_id": "",
"customer_id": "",
"status": "pending_activation",
"sub_status": "document_submission_required",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"transaction_status": "",
"transaction_sub_status": "",
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "UNKNOWN",
"kyc_processed_date": "",
"date_created": "2026-05-05T14:25:49Z",
"date_updated": "0001-01-01T00:00:00Z",
"pending_update": [],
"verification_id": {},
"require_provider_update": [],
"http_status_code": 0,
"requirements": {
"immediately_due": {
"required_attributes": [],
"required_actions": []
},
"eventually_due": {
"required_attributes": [],
"required_actions": []
},
"pending_verification": {}
},
"risk_assesment_status": "UNKNOWN",
"status_reason_code": "",
"status_message": "",
"business_id": "9fcc5c86a79f4bf18ab69f435ca66b10"
}Create (Sub-business) Individual User - Providing complete user infomation
Create (Sub-business) Individual User - Providing complete user infomation
Region-specific Onboarding
The example below displays the exhaustive set of user information fields that can be passed through the Create Sub-Business User endpoint.
However, since this endpoint is utilized for multiple regions with different regulatory requirements, usage per region will differ.
Partners are encouraged to refer to the Region-specific Onboarding section to see the list of information required for their program region.
Only the listed region-specific user information is required to be collected from the users and submitted for user registration.
Create (Sub-business) Individual User request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/businesses/{{parent_business_id}}/users' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data-raw '{
"client_ref_id": "9234567891",
"provider_action_id": "111224555",
"preferred_name": "Jane",
"salutation": "ms",
"title": "dr",
"first_name": "Jane",
"legal_name": "Jane Smith",
"alias_name": "",
"tin": "122334aaa",
"middle_name": "Williams",
"last_name": "Smith",
"maiden_name": "Jane Steven",
"gender": "FEMALE",
"marital_status": "MARRIED",
"email": "jane.smith@matchmove.com",
"mobile_country_code": "65",
"mobile": "91118888",
"provider_data": {
"test_identifier": "124ed23"
},
"supporting_documents": [
{
"id_number": "M414L7116",
"id_type": "AGREEMENT",
"id_issuance_country": "DNK",
"id_sub_type": "abc",
"id_issuer_name": "passport authority",
"id_issuer_code": "PA",
"id_issuer_state": "TN",
"is_term_unlimited": false,
"is_expiry_extended": false
}
],
"identification": {
"primary": {
"id_number": "test",
"id_type": "ID_CARD",
"id_date_added": "2019-08-24",
"id_date_issued": "2025-06-08",
"id_date_expiry": "2028-08-24",
"id_issuance_country": "DNK"
},
"secondary": {
"id_number": "last name",
"id_type": "DRIVERS_ID",
"id_date_added": "2019-08-24",
"id_date_issued": "2025-06-08",
"id_date_expiry": "2028-08-24",
"id_issuance_country": "DNK"
}
},
"birth": {
"name": "Louie Miranda",
"date": "2000-04-02",
"city": "Gen Trias",
"country": "PHL",
"postal_code": "1000"
},
"nationality": "AFGHAN",
"mothers_details": {
"first_name": "Est",
"middle_name": "Tori",
"last_name": "Mir",
"maiden_name": "e t m"
},
"fathers_details": {
"first_name": "Vir",
"middle_name": "Cab",
"last_name": "Mir",
"maiden_name": "v c m"
},
"addresses": {
"residential": {
"line_1": "123",
"line_2": "Flywheel St",
"line_3": "",
"line_4": "",
"city": "GABALDON_BITULOK_SAB",
"state": "LAUNION",
"state_code": "123",
"country": "DNK",
"postal_code": "2200"
},
"billing": {
"line_1": "123",
"line_2": "Flywheel St",
"line_3": "",
"line_4": "",
"city": "ABORLAN_PALAWAN",
"state": "Cavite",
"country": "DNK",
"postal_code": "4107"
},
"shipping": {
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"city": "ABORLAN_PALAWAN",
"country": "DNK",
"state": "Cavite",
"postal_code": "4107"
}
},
"employment_type": "SELF-EMPLOYED",
"job_title": "ACCOUNTANT",
"employment_details": {
"business_purpose": "ACCOUNTING",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "Manila",
"expected_monthly_revenue": "1000000",
"vat_number": "893678372",
"business_address": {
"line_1": "123",
"line_2": "Flywheel St",
"line_3": "",
"line_4": "",
"city": "ABORLAN_PALAWAN",
"country": "DNK",
"state": "Cavite",
"postal_code": "4107"
}
},
"fatca_crs_confirmed_at": "2019-08-24T14:15:22Z",
"fatca_relevant": true,
"annual_income_range": "20000",
"main_income_source": "SALARY",
"socioprofessional_category": "string",
"purpose_of_account_opening": "CASH_DEPOSIT",
"work_country": "Philippines",
"residency_country": "Philippines",
"self_declared_as_pep": true,
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Curl",
"device_id": "SteveOS-High"
},
"provider_ref_id": "",
"provider_account_number": "",
"posting_status": "ok",
"data_terms_signed_at": "2022-06-15 00:00:00",
"metadata": {
"test_identifier": "aaabbbb"
},
"created_by": "bot@matchmove.com"
}'Create (Sub-business) Individual User response
JSON
{
"id": "c498924262844a9a9dd46c12848a4e70",
"type": "individual",
"client_ref_id": "9234567891",
"provider_ref_id": "",
"provider_account_number": "",
"salutation": "ms",
"title": "Dr",
"first_name": "Jane",
"middle_name": "Williams",
"last_name": "Smith",
"preferred_name": "Jane",
"email": "jane.smith@matchmove.com",
"mobile_country_code": "65",
"mobile": "91118888",
"gender": "Female",
"marital_status": "Married",
"identification": {
"primary": {
"id_number": "test",
"id_type": "Id Card",
"id_date_issued": "2025-06-08",
"id_date_expiry": "2028-08-24",
"id_issuance_country": "Denmark"
},
"secondary": {
"id_number": "last name",
"id_type": "Driver's license",
"id_date_issued": "2025-06-08",
"id_date_expiry": "2028-08-24",
"id_issuance_country": "Denmark"
}
},
"birth": {
"name": "Louie Miranda",
"date": "2000-04-02",
"city": "Gen Trias",
"country": "Philippines",
"postal_code": "1000"
},
"nationality": "Nationality for Afghanistan",
"mothers_details": {
"first_name": "Est",
"middle_name": "Tori",
"last_name": "Mir",
"maiden_name": "e t m"
},
"father_details": {
"first_name": "Vir",
"middle_name": "Cab",
"last_name": "Mir",
"maiden_name": "v c m"
},
"addresses": {
"residential": {
"line_1": "123",
"line_2": "Flywheel St",
"city": "GABALDON_BITULOK_SAB",
"state": "LAUNION",
"state_code": "123",
"postal_code": "2200",
"country": "Denmark"
},
"billing": {
"line_1": "123",
"line_2": "Flywheel St",
"city": "ABORLAN_PALAWAN",
"state": "Cavite",
"postal_code": "4107",
"country": "Denmark"
},
"shipping": {
"line_1": "Cusiness_@#164654,: jkjsdj lkshj",
"line_2": "Cusiness_@#164654,: jkjsdj lkshj",
"line_3": "Cusiness_@#164654,: jkjsdj lkshj",
"line_4": "BARMM",
"city": "ABORLAN_PALAWAN",
"state": "Cavite",
"postal_code": "4107",
"country": "Denmark"
},
"identity_verification": {},
"foundation": {},
"operational": {}
},
"employment_type": "Self Employed",
"job_title": "Accountant",
"employment_details": {
"business_trading_name": "",
"business_purpose": "ACCOUNTING",
"industry": "Finance & Tech",
"industry_key": "fintech",
"own_economic_interest_signed_at": "Manila",
"expected_monthly_revenue": "1000000",
"vat_number": "893678372",
"business_address": {
"line_1": "123",
"line_2": "Flywheel St",
"postal_code": "4107",
"city": "ABORLAN_PALAWAN",
"country": "Denmark",
"state": "Cavite"
}
},
"fatca_crs_confirmed_at": "0001-01-01T00:00:00Z",
"fatca_relevant": false,
"data_terms_signed_at": "",
"annual_income_range": "20000",
"main_income_source": "Salary",
"purpose_of_account_opening": "Cash Deposit",
"socioprofessional_category": "",
"work_country": "Philippines",
"residency_country": "Philippines",
"self_declared_as_pep": false,
"tos_acceptance": {
"date": "2019-08-24T14:15:22Z",
"ip": "192.168.0.1",
"service_agreement": "terms_condition",
"user_agent": "Curl",
"device_id": "SteveOS-High"
},
"metadata": null,
"agent_id": "",
"partner_id": "",
"customer_id": "",
"status": "active",
"sub_status": "active",
"kyc_status": "not_submitted",
"kyc_sub_status": "",
"transaction_status": "",
"transaction_sub_status": "",
"is_email_verified": "1",
"is_mobile_verified": "1",
"is_risk_flagged": "UNKNOWN",
"kyc_processed_date": "",
"date_created": "2026-02-11T12:40:46Z",
"date_updated": "0001-01-01T00:00:00Z",
"pending_update": [],
"verification_id": {},
"require_provider_update": [],
"http_status_code": 0,
"requirements": {
"immediately_due": {
"required_attributes": [],
"required_actions": []
},
"eventually_due": {
"required_attributes": [],
"required_actions": []
},
"pending_verification": {}
},
"risk_assesment_status": "UNKNOWN",
"status_reason_code": "",
"status_message": "",
"business_id": "be9db48068c4455782067426fdccd90b",
"legal_name": "Jane Smith",
"tin": "122334aaa",
"supporting_documents": [
{
"id_number": "M414L7116",
"id_type": "Agreement",
"id_sub_type": "abc",
"id_issuance_country": "Denmark",
"id_issuer_name": "passport authority",
"id_issuer_code": "PA",
"id_issuer_state": "TN"
}
]
}Field notes:
preferred_nameis usually the (First Name + Last Name), which will be used as the default cardholder name for card programs. For non-card programs, we can just pass the same, just to satisfy the API requirement.
User identifier as a partner foreign key
When a new individual user is created, a user identifier (user.id) will be generated. In the example above, the user identifier will be the "id": "cd896adb395fa384a5a8b174a007c34c".
It is recommended that you store this MatchMove user identifier in your internal database and map it with your users. This user identifier will be heavily used in most post-user creation API, and it will be convenient for you to have it accessible.
2
[Conditional] Email and mobile verification
As per the regulation and security considerations, all users that will be onboarded in the platform must have their mobile and email verified.
Depending on the program region, this verification requirement may be imposed at the platform level and block the onboarding progress unless verification is completed.
A. Partner mobile and email self-verification
Programs not requiring “Platform-level mobile and email verification” may proceed with their own verification using their internal capability or through external services.
Partner Email and Mobile Verification Confirmation
Partner Email and Mobile Verification Confirmation
After you have verified the user email and mobile using your own verification system, you will need to confirm it with the platform.
Email Self-Verification request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify/otp' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"method": "email",
"email": "john.smith@matchmove.com"
}'Mobile Self-Verification request
CURL
curl --location 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify/otp' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"method": "sms",
"mobile_number": "9339924187",
"mobile_country_code" : "63"
}'B. Platform-level mobile and email verification
A program requiring API-level email and mobile verification will be moved to a "status": "pending_verification" in the Create User response or user object.
Partners may be able to use the platform to send a one-time PIN (OTP) challenge to the customer's email or mobile number that is being verified.
MatchMove Email and Mobile Verification
MatchMove Email and Mobile Verification
Trigger Mobile Verification / Trigger Email Verification
Call Trigger Mobile Verification (POST /users/trigger/otp/sms) or Trigger Email Verification (POST /users/triggers/otp/email)
to initiate or trigger the platform to send a verification request and send an OTP code to the customer.
Trigger Mobile Verification request
CURL
curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/trigger/otp/sms' \
--header 'X-Auth-User-ID: <user_id>' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••'Trigger Mobile Verification response
JSON
{ "email" : "john.smith@matchmove.com" ,
"expires_at" : "2019-08-24T14:15:22Z" ,
"method" : "SMS" ,
"retry_after" : "1000" ,
"verification_code" : "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwiaGFzaF9pZCI6IiIsIlByb2dyYW1Db2RlIjoicGhhdWJkZW0iLCJNZXRob2QiOiIiLCJFbWFpbElEIjoiIiwiTW9iaWxlTnVtYmVyIjoiIiwiTW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRpb25Ub2tlbiI6IiIsIklzQWN0aXZlIjpmYWxzZSwiT1RQIjoiMjY1MTM2IiwiaXNzIjoiTWF0Y2htb3ZlIiwic3ViIjoiT1RQIiwiZXhwIjoxNjY1NDYxODQ3LCJuYmYiOjE2NjU0NjE3NDcsImlhdCI6MTY2NTQ2MTc0NywiRXhwaXJlc0F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJSZXNlbmRBZnRlciI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiQ3JlYXRlZEF0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoifQ.vf-mqmasUksU1e0vah8RO-YFic58tP-2HTUN5eHYkUPli2jephYaan0h8wMDLKID469Y85gQIGym7WmYj4TMJA " , "mobile_country_code" : "63",
"mobile_number" : "9999999999" }Trigger Email Verification request
CURL
curl --location --request POST 'https://{{identity_base_url}}/{{program_code}}/v2/users/trigger/otp/email' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••'Trigger Email Verification response
JSON
{ "email" : "john.smith@matchmove.com" ,
"expires_at" : "2019-08-24T14:15:22Z" ,
"method" : "EMAIL" ,
"retry_after" : "1000" ,
"verification_code" : "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwiaGFzaF9pZCI6IiIsIlByb2dyYW1Db2RlIjoicGhhdWJkZW0iLCJNZXRob2QiOiIiLCJFbWFpbElEIjoiIiwiTW9iaWxlTnVtYmVyIjoiIiwiTW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRpb25Ub2tlbiI6IiIsIklzQWN0aXZlIjpmYWxzZSwiT1RQIjoiMjY1MTM2IiwiaXNzIjoiTWF0Y2htb3ZlIiwic3ViIjoiT1RQIiwiZXhwIjoxNjY1NDYxODQ3LCJuYmYiOjE2NjU0NjE3NDcsImlhdCI6MTY2NTQ2MTc0NywiRXhwaXJlc0F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJSZXNlbmRBZnRlciI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiQ3JlYXRlZEF0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoifQ.vf-mqmasUksU1e0vah8RO-YFic58tP-2HTUN5eHYkUPli2jephYaan0h8wMDLKID469Y85gQIGym7WmYj4TMJA " , "mobile_country_code" : "63",
"mobile_number" : "9999999999" }Once the OTP is received, partners must ask the customer to provide the OTP code and verify it against the OTP sent by the platform.
This verification must be completed before the OTP code expires. The expiry period can be configured in the program and is set to 5 minutes by default.
The verification process will require you to pass the encrypted OTP code (provided by the customer) and the verification code (returned by the Trigger SMS/Email Verification response).
OTP Code Encryption Logic:
Encryption algorithm: AES CBC 256-bit, with no Initial Vector (IV)Encryption key: Use the “Basic Authentication username: password” hashIV: Use the first 16 characters of the encryption keyEncoding: Use Hex encoding
Sample encrption code (Go):
Go
package main
import (
"bytes"
"crypto/aes"
"crypto/cipher"
"encoding/base64"
"fmt"
"strings"
)
const IV = "NDMbfRhOsN3QNGKx"
const KEY = "zDYWhP5keEvuGMWxlWBQCym43jIBYKJY"
func main() {
EncryptTest("926946")
}
func EncryptTest(plaintext string) {
key := []byte(KEY)
encryptAES, _ := EncryptAES(plaintext, key, []byte(IV))
_, err := DecryptAES(encryptAES, key, []byte(IV))
if err != nil {
fmt.Println(err.Error())
}
fmt.Println("result: " + encryptAES)
}
// EncryptAES Encrypts the given plain text using the given key
// returns a hex encoded string of the AES encrypted string
func EncryptAES(content string, encryptionKey []byte, IV []byte) (string, error) {
paddedPlaintext := PKCS5Padding([]byte(content), aes.BlockSize)
block, err := aes.NewCipher(encryptionKey)
if err != nil {
return "", err
}
ciphertext := make([]byte, len(paddedPlaintext))
mode := cipher.NewCBCEncrypter(block, IV)
mode.CryptBlocks(ciphertext, paddedPlaintext)
return base64.StdEncoding.EncodeToString(ciphertext), nil
}
// DecryptAES decrypts a given hex encoded AES encrypted string
// using the key given
func DecryptAES(cipherText string, encryptionKey []byte, IV []byte) (string, error) {
block, err := aes.NewCipher(encryptionKey)
if err != nil {
return "", err
}
c, err := base64.StdEncoding.DecodeString(cipherText)
if err != nil {
return "", err
}
mode := cipher.NewCBCDecrypter(block, IV)
mode.CryptBlocks(c, c)
return strings.TrimSpace(string(c)), err
}
// PKCS5Padding adds the necessary padding for the given
// data
func PKCS5Padding(cipherText []byte, blockSize int) []byte {
padding := blockSize - len(cipherText)%blockSize
padText := bytes.Repeat([]byte{byte(padding)}, padding)
return append(cipherText, padText...)
}Verify OTP
Call Verify OTP (PUT /users/verify/otp) passing the encrypted OTP code and the verification code to initiate verification.
Verify OTP request
CURL
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v2/users/verify/otp' \
--header 'X-Auth-User-ID: {{user_id}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: ••••••' \
--data '{
"otp": "TW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRp",
"verification_code": "eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJpZCI6MCwiaGFzaF9pZCI6IiIsIlByb2dyYW1Db2RlIjoicGhhdWJkZW0iLCJNZXRob2QiOiIiLCJFbWFpbElEIjoiIiwiTW9iaWxlTnVtYmVyIjoiIiwiTW9iaWxlQ291bnRyeUNvZGUiOiIiLCJWZXJpZmljYXRpb25Ub2tlbiI6IiIsIklzQWN0aXZlIjpmYWxzZSwiT1RQIjoiMjY1MTM2IiwiaXNzIjoiTWF0Y2htb3ZlIiwic3ViIjoiT1RQIiwiZXhwIjoxNjY1NDYxODQ3LCJuYmYiOjE2NjU0NjE3NDcsImlhdCI6MTY2NTQ2MTc0NywiRXhwaXJlc0F0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoiLCJSZXNlbmRBZnRlciI6IjAwMDEtMDEtMDFUMDA6MDA6MDBaIiwiQ3JlYXRlZEF0IjoiMDAwMS0wMS0wMVQwMDowMDowMFoifQ.vf-mqmasUksU1e0vah8RO-YFic58tP-2HTUN5eHYkUPli2jephYaan0h8wMDLKID469Y85gQIGym7WmYj4TMJA"
}'Verify OTP response
JSON
{
"status": "success",
"message": "Verification completed successfully"
}Related Links
Was this section helpful?
On this page
- Register individual profile