Register business profile
The Register business profile section is designed to streamline the process for businesses to get started on our platform. Users can easily create and manage their business profiles and access essential features to kickstart their operations.
Use Cases
- You want to onboard a business user who is a business or corporate entity, not a natural person.
- You want to onboard a business user who will use an account for business purposes.
- You want to onboard a business user who is a sub-entity (sub-account) of the main program partner.
- You want to onboard a business user who is a corporate client (sub-account) of the main program partner.
- You want to onboard a business user who is a corporate client sub-entity (client sub-account) of your corporate client (sub-account).
Prerequisites
- Before starting to collect business 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.
- Collect business information from the corporate 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.
Business User data
The data that needs to be collected from the business can be broken down into these groups:
- Business profile and legal identifiers - Vital identity information is required to create a user in the system. These will include legal business names, representative contacts, and other relevant details.
- Business demographics details - Additional statistics, foundation, and operational addresses of the business entity.
API Workflow (v1)
1
Create a business user profile in the program
You can start registering a business profile when the business profile and legal identifiers are ready.
Call Create Business User (POST /businesses) to create a business profile for the corporate entity that you are onboarding.
Create Business User API-required fields enumerations:
mobile_country_codeallowed values are listed in the Mobile Country Code Enumeration (GET /users/enumerations/mobile_country_code).tax_id_typeallowed values are listed in the Business ID Types Enumeration (GET /users/enumerations/business_id_types).source_of_fundsvalues are listed in the Source of Funds Enumeration (GET /users/enumerations/business_source_of_funds).tax_identification.issuance_countryallowed values are listed in the Countries Enumeration (GET /users/enumerations/countries). Use the country code.purpose_of_account_openingallowed values are listed in the Purpose of Account Enumeration (GET /users/enumerations/business_purpose_of_account).
*These enumerations are all part of the Identity API category; you can access them by using the {{identity_base_url}}. See Utilize Enumerations section to learn more.
Create Business User request
curl --location 'https://{{identity_base_url}}/{{program_code}}/v1/businesses' \
--header 'Content-Type: application/x-www-form-urlencoded' \--header 'Authorization: ••••••' \
--data-urlencode 'name="XYZ Corp"' \
--data-urlencode 'preferred_name="XYZ Corp"' \
--data-urlencode 'mobile_country_code="65"' \
--data-urlencode 'mobile="88888888"' \
--data-urlencode ‘email=corporate@xyz.com' \--data-urlencode ‘role=SUB_PARTNER_USER' \
--data-urlencode 'tax_id_number=AA12345' \
--data-urlencode 'tax_id_type=tin' \
--data-urlencode 'foundation_date=2019-08-24' \
--data-urlencode 'tax_id_date_issued=2019-08-24' \
--data-urlencode 'tax_id_date_expiry=2025-08-24' \
--data-urlencode 'tax_id_issuance_country=SGP'Create Business User response
{
"id": "121a84f24763990b12a6c55e2993ac4a",
"account_type": "business",
"email": "corporate@xyz.com",
"name": {
"business": "XYZ Corp",
"preferred": "XYZ Corp"
},
"mobile": {
"country_code": "65",
"number": "88888888"
},
"status": {
"is_active": false,
"text": "inactive",
"state": "pending"
},
"foundation_date": "",
"date": {
"registration": "2025-07-24T11:56:59+08:00"
},
"client_ref_id": "", "role"="SUB_PARTNER_USER",
"source_of_funds": "BUSINESS",
"purpose_of_account_opening": "",
"additional_details": "",
"tax_identification": {
"type": "tin",
"number": "AA12345",
"issuance_country": "",
"date_issued": "2019-08-24",
"date_expiry": "2025-08-24"
},
"role": "End User",
"risk_assessment_status": "CLEARED"
}Business user identifier as a partner foreign key
When a new business user is created, a user identifier (user.id) will be generated. In the example above, the user identifier will be the "id": "121a84f24763990b12a6c55e2993ac4a".
It is recommended that you store this MatchMove user identifier in your internal database and map it with your users. This business user identifier will be heavily used in most post-user creation API, and it will be convenient for you to have it accessible.
2
Update the foundation and operational address of the business
The foundation address type (mandatory) refers to the address where the business was incorporated or established.
The operational address type (optional) refers to the address currently used as the center of business.
Call Update Business Addresses (PUT /businesses/addresses/foundation) to update the foundation address of the business.
Update Business request (foundation address)
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/addresses/foundation' \
--header 'X-Auth-User-ID: {{business_user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'address_1=50' \
--data-urlencode 'address_2=Sunrise St.78' \
--data-urlencode 'city=01-01' \
--data-urlencode 'state=Singapore' \
--data-urlencode 'country=Singapore' \
--data-urlencode 'country_code=SGP' \
--data-urlencode 'zipcode=399999'curlUpdate Business response (foundation address)
{
"foundation": {
"address_1": "50",
"address_2": "Sunrise St.78",
"city": "01-01",
"country": "Singapore",
"country_code": "SGP",
"state": "Singapore",
"zipcode": "399999"
}
}Call Update Business Addresses (PUT /businesses/addresses/operational) to update the operational address of the business. The operational address can be the same as the foundation address.
Update Business request (operational address)
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/addresses/operational' \
--header 'X-Auth-User-ID: {{business_user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'address_1=50' \
--data-urlencode 'address_2=Sunrise St.78' \
--data-urlencode 'city=01-01' \
--data-urlencode 'state=Singapore' \
--data-urlencode 'country=Singapore' \
--data-urlencode 'country_code=SGP' \
--data-urlencode 'zipcode=399999'Update Business response (operational address)
{
"operational": {
"address_1": "50",
"address_2": "Sunrise St.78",
"city": "01-01",
"country": "Singapore",
"country_code": "SGP",
"state": "Singapore",
"zipcode": "399999"
}
}3
Prepare for the KYB submission process
The data for connected parties and beneficial owners will usually be enclosed inside the uploaded KYB documents and not directly accessible unless the documents are reviewed.
So to aid faster identification of these individuals and connected entities for KYB approval and audits, we will need to prepare at least their basic details and add them to the business profile. Since all data passed to the business profile will directly be viewable in the administrator dashboard by the MatchMove Compliance team for review.
When available, the details of the connected parties and beneficial owners can be passed through the additional_details field of the business profile. You can use the Create Business User (during initial profile creation) or the Update Business User (as a profile update) endpoint to pass these details.
Business user profile additional_details template:
{
"beneficial_owners": [
{
"entity_type": "individual | business",
"ownership_percentage": "0 to 100",
"business_name": "mandatory if entity_type = business, else NA",
"foundation_date": "mandatory if entity_type = business, format = YYYY-MM-DD, else NA",
"shareholder": {
"type": "owner | authorized_signatory",
"first_name": "mandatory",
"middle_name": "optional, else blank",
"last_name": "mandatory",
"dob": "YYYY-MM-DD"
}
},
..
]}Call Update Business User (PUT /businesses) to update the business profile with the additional details that will be required for full KYB verification.
Update Business User request (additional_details)
curl --location --request PUT 'https://{{identity_base_url}}/{{program_code}}/v1/businesses/{{business_user_id}}' \
--header 'X-Auth-User-ID: {{business_user_id}}' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: ••••••' \
--data-urlencode 'additional_details={
"beneficial_owners": [
{
"entity_type": "individual",
"ownership_percentage": "10",
"business_name": "NA",
"foundation_date": "NA",
"shareholder": {
"type": "owner",
"first_name": "John",
"middle_name": "",
"last_name": "Smith",
"dob": "1980-01-01"
}
}
]
}'Update Business User response (additional_details)
{
"id": "121a84f24763990b12a6c55e2993ac4a",
"account_type": "business",
"email": "corporate@xyz.com",
"name": {
"business": "XYZ Corp",
"preferred": "XYZ Corp"
},
"mobile": {
"country_code": "65",
"number": "88888888"
},
"status": {
"is_active": false,
"text": "inactive",
"state": "pending"
},
"foundation_date": "",
"date": {
"registration": "2025-07-24T11:56:59+08:00"
},
"client_ref_id": "",
"source_of_funds": "BUSINESS",
"purpose_of_account_opening": "",
"additional_details": {
"beneficial_owners": [
{
"entity_type": "individual",
"ownership_percentage": "10",
"business_name": "NA",
"foundation_date": "NA",
"shareholder": {
"type": "owner",
"first_name": "John",
"middle_name": "",
"last_name": "Smith",
"dob": "1980-01-01"
}
}
]
},
"tax_identification": {
"type": "tin",
"number": "AA12345",
"issuance_country": "",
"date_issued": "2019-08-24",
"date_expiry": "2025-08-24" },
"role": "End User",
"risk_assessment_status": "CLEARED"
"risk_assessment_status": "CLEARED"Related Links
On this page
- Register business profile