Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewUnderstanding Global Treasury
Market & infrastructure coverage
Use cases
Hold & convert funds
Connected accounts
Connected accounts overviewKYC and onboarding
Embedded KYC componentHosted onboardingNative API
Simulate connected account status transition
Handle KYC RFI
Onboard multiple connected accountsMove funds between accounts
Compliance and Outsourcing requirements
Error codes
Test and go live

Native API

Learn how to create and activate connected accounts using Native API, including handling KYC requirements using this step-by-step tutorial.

Step 1: Create connected accounts

Connected accounts that you create via Accounts API will be linked to your Platform and you will have authorization to transact on behalf of the connected account using Airwallex's Scale APIs.


By confirming agreement to Airwallex's terms and conditions, you consent to the terms covering the relationship between Airwallex, your business and the counterparty on whose behalf you are opening the account, and in doing so, Airwallex is authorised to take action on the connected account according to your instructions.

The response includes the Airwallex account ID for the connected account, which you will use in the next steps.

Step 2: Update and submit account for KYC

Determine data required for KYC (for API submission only)

To determine the information you need to collect from your users, please review the KYC requirements for business and individual .

All required fields have to be filled before activating the account. Filling in optional fields before activating the account will increase the success rate of account activation. You may collect the required fields from users using your user interface, or use information previously collected or determined from your own data (e.g., monthly transaction volumes).

Attach data & documents for KYC

Documents may be uploaded to the Airwallex server using the File service API. The response of the file service API endpoint will include a file_id, which you should save so that you can reference it in the next step. Once all documents have been successfully uploaded, you can proceed.


Accounts may be created & updated in stages using Accounts API.

Creating an empty account and updating the required information step-by-step is useful if you do not store a copy of the information on your server and you aim to have the user provide information to your Platform in stages.

You can start out with creating an empty account via Accounts API, for which you only need to provide three pieces of information:

  • Primary contact of the user (either email or mobile phone number)
  • Agreement to data sharing
  • Agreement to terms and conditions

An example response:


Afterwards you can add any information collected from the user with the update Accounts API. You can replace {account_id} with the account id received when creating the empty account, to identify the account to which you want to add or change information.

You can call the update account endpoint as many times as you wish until all the information required has been added. You can also use the update account endpoint to overwrite information previously added.


Submit the account for activation

Once all the required information has been collected, you can submit the account for activation using <POST /api/v1/accounts/{account_id}/submit>. If the information provided fulfills the requirements determined in step 1, the account status will be updated to SUBMITTED.


You can subscribe to account update webhooks to be notified once the activation has been completed. For individuals, most accounts will be activated within a minute. However, if further review is required, the activation may take 24 hours or longer. Alternatively, you can query the status of the account using <GET /api/v1/accounts/{account_id}> and look at the field at any time.


If the information you have provided is not sufficient based on the requirements determined in the first step, the call <POST /api/v1/accounts/{account_id}/submit> will respond with the error code below: 400 Possible errors: field_required, invalid_argument

Example response:


Step 3: Handle additional requests for Information (RFI)

Sometimes more steps are required to successfully complete the account activation, even if the information you submitted in step 2 was initially deemed sufficient. There are generally two reasons this might happen:

  • Failed identity verification: During KYC we have to verify the identity of the individual. If we are unable to verify the identity, you’ll need to ask the individual to submit a second form of identification, or retry after correcting any errors in the previously submitted data.
  • Additional information requests: During KYC, we have to assess the risk of each individual, in order to decide whether the account can be activated or not. In some instances, more information will be required to make that decision.

Read this document to find out more about our RFI options to handle additional information requests for KYC.

On this page