Quickstart: Your first connected account

This quickstart guides you through creating your first connected account using the Airwallex API. You'll learn how to authenticate, create an account, and check its status. This provides the foundation for building your full connected accounts integration.

Before you begin

Ensure you have:

• An Airwallex platform account. If connected accounts capabilities are not enabled, contact your Airwallex Account Manager to request enablement. Your Account Manager confirms when the capability is on.
• API credentials. You'll need your client ID and API key.
• Access to the sandbox environment for testing.
• Basic familiarity with making API requests using cURL, Postman, or your preferred HTTP client.

Step 1: Authenticate and get an access token

All API requests require authentication. First, obtain an access token using your API credentials.

1curl -X POST https://api.sandbox.airwallex.com/api/v1/authentication/login \
2  -H 'Content-Type: application/json' \
3  -H 'x-client-id: YOUR_CLIENT_ID' \
4  -H 'x-api-key: YOUR_API_KEY'

1{
2  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
3  "expires_at": "2026-02-02T12:00:00Z"
4}

Save the token value—you'll use it in subsequent API requests as a Bearer token in the Authorization header.

Step 2: Create a connected account

Create a connected account for an individual customer using the Create connected accountAPI endpoint.

This quickstart creates a connected account for an individual. You must agree to Airwallex's terms and conditions on behalf of the account holder before creating the account.

1curl -X POST https://api.sandbox.airwallex.com/api/v1/accounts/create \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "account_details": {
6      "legal_entity_type": "INDIVIDUAL",
7      "individual_details": {
8        "residential_address": {
9          "country_code": "AU"
10        }
11      }
12    },
13    "customer_agreements": {
14      "agreed_to_data_usage": true,
15      "agreed_to_terms_and_conditions": true
16    },
17    "primary_contact": {
18      "email": "[email protected]"
19    }
20  }'

1{
2  "id": "acct_hkdmCy9wnfEJjMHNxINdC",
3  "status": "CREATED",
4  "account_details": {
5    "legal_entity_type": "INDIVIDUAL",
6    "individual_details": {
7      "first_name": null,
8      "last_name": null,
9      "nationality": null,
10      "residential_address": {
11        "country_code": "AU"
12      }
13    }
14  },
15  "primary_contact": {
16    "email": "[email protected]"
17  },
18  "customer_agreements": {
19    "agreed_to_data_usage": true,
20    "agreed_to_terms_and_conditions": true
21  },
22  "created_at": "2026-02-02T10:30:00Z"
23}

The response shows:

• A connected account created with status CREATED.
• The account ID starts with acct_ prefix.
• The account is ready to be updated with additional details for identity verification.

Step 3: Check account status

Check the connected account's status using the Get connected accountAPI endpoint.

1curl -G https://api.sandbox.airwallex.com/api/v1/accounts/acct_hkdmCy9wnfEJjMHNxINdC \
2  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

1{
2  "id": "acct_hkdmCy9wnfEJjMHNxINdC",
3  "status": "CREATED",
4  "account_details": {
5    "legal_entity_type": "INDIVIDUAL",
6    "individual_details": {
7      "first_name": null,
8      "last_name": null,
9      "nationality": null,
10      "date_of_birth": null,
11      "residential_address": {
12        "country_code": "AU"
13      }
14    }
15  },
16  "primary_contact": {
17    "email": "[email protected]"
18  },
19  "customer_agreements": {
20    "agreed_to_data_usage": true,
21    "agreed_to_terms_and_conditions": true
22  },
23  "created_at": "2026-02-02T10:30:00Z"
24}

The account remains in CREATED status until you collect and submit identity information. The account status field transitions through these values as the account lifecycle progresses:

• CREATED: Account created but not yet submitted for verification (current status).
• SUBMITTED: Account submitted for onboarding verification review (after submitting identity information).
• ACTIVE: Account verified and fully operational (after successful onboarding verification).
• SUSPENDED: Account disabled, failed verification, or temporarily suspended by the platform. After a completed offboarding, the account enters pending closure and also appears as SUSPENDED on all API versions.
• DORMANT: Available from API version 2026-08-21. The account is dormant due to prolonged inactivity and must initiate a transaction to trigger a reactivation review before it becomes active again.
• CLOSED: Available from API version 2026-08-21. The account is permanently closed after the pending-closure grace period and cannot be reactivated. On earlier API versions, closed accounts are returned as SUSPENDED.

Platforms can raise an account closure request using Create an offboardingAPI for a connected account that is not already closed or pending closure. Create Offboarding is not limited to ACTIVE accounts. This triggers the official Ops-owned offboarding workflow. To temporarily disable an account without starting offboarding, use Suspend accountAPI instead. That status change is recoverable with Reactivate accountAPI. While the offboarding request is in progress, the account status does not change. After the offboarding completes successfully (COMPLETED), the account enters pending closure and the client API returns SUSPENDED on all API versions. After a 30-day grace period, the account is permanently closed. From API version 2026-08-21, that surfaces as CLOSED. On earlier versions, it remains SUSPENDED.

You can also subscribe to account status and offboarding webhooks to be notified of status changes automatically.

Next steps

You've successfully created your first connected account. The account is in CREATED status and needs onboarding verification—previously referred to as Know Your Customer (KYC)—before it can process transactions. To choose an onboarding verification integration approach and build your production integration, see Plan your path to production.