Custom fields via API

Create, list, retrieve, and update custom accounting fields and their values programmatically using the custom fields APIs.

Copy for LLMView as Markdown

The custom fields API lets you manage additional accounting dimensions in Airwallex Spend, such as projects or cost centers. Each custom field has one or more selectable values. Sync fields and values from your ERP or accounting system so employees and automated workflows can code expenses, bills, and other Spend items with the correct dimensions.

Before you begin

Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You can create scoped API keys in Settings > Developer > API keys in the Airwallex web app. Spend resources require Organization-level permissions.
Set up custom accounting data for an overview of accounting data concepts, including external IDs, legal entity scope, and status.

Sync custom fields from your ERP

Custom accounting data has two levels: the field (for example, Custom field 1, with display name Project) and the values within it (for example, PRJ-001). A typical sync workflow looks like this:

List existing custom fields in Airwallex.
Create fields for ERP dimensions that are not yet configured in Airwallex. Before creating a field, list existing fields and confirm which field (Custom field 1 through Custom field 5) is available.
For each field, use the field id from the list or create response as accounting_field_id when listing, creating, and updating values. Match records using external_id.
Set status to ARCHIVED on update for values that are no longer active in your ERP.

Create the parent field before creating its values.

Create a custom field

To create a custom accounting field, call the Create accounting field API endpoint. Airwallex provides five custom fields. Set name to the field name — exactly one of Custom field 1, Custom field 2, Custom field 3, Custom field 4, or Custom field 5 (values are case-sensitive). Set name_label to the display name shown in the Airwallex web app (for example, Project). Use name as field_id when coding transactions via the Spend API. If a field with that name already exists, the create request fails. When syncing from your ERP, list existing fields first and create only those that are missing.

Send the create request with the field name as name and the display name as name_label:
Shell
```
1curl -X POST \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_fields/create' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "request_id": "985461d5-016f-4e1f-a387-5f1380b42d92",
7    "name": "Custom field 1",
8    "name_label": "Project"
9  }'
```

The response returns the created field with its unique Airwallex id:

JSON

1{
2  "id": "da66f0ff-8081-4db6-8333-4e011fe9561f",
3  "name": "Custom field 1",
4  "name_label": "Project",
5  "status": "ACTIVE",
6  "created_at": "2026-06-15T00:00:00Z",
7  "updated_at": "2026-06-15T00:00:00Z"
8}

List custom fields

To retrieve custom fields, call the List accounting fields API endpoint.

Send the request with optional filters:

Shell

1curl -G \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_fields' \
3  --data-urlencode 'status=ACTIVE' \
4  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

The response returns a paginated list of custom fields:

JSON

1{
2  "items": [
3    {
4      "id": "da66f0ff-8081-4db6-8333-4e011fe9561f",
5      "name": "Custom field 1",
6      "name_label": "Project",
7      "status": "ACTIVE",
8      "created_at": "2026-06-15T00:00:00Z",
9      "updated_at": "2026-06-15T00:00:00Z"
10    }
11  ],
12  "page_after": "string",
13  "page_before": "string"
14}

Key query parameters include:

Parameter	Description
`status`	Filter by `ACTIVE` or `ARCHIVED`.
`page`	A bookmark for pagination. Use the value from `page_after` or `page_before` in the previous response.

Get custom field details

To retrieve a specific custom field, call the Get accounting field API endpoint.

Use the id from the list or create response:

Shell

1curl -G \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_fields/{{FIELD_ID}}' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Update a custom field

To update an existing custom field, call the Update accounting field API endpoint.

Send the update request with the fields you want to change:

Shell

1curl -X POST \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_fields/{{FIELD_ID}}/update' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "name": "Custom field 1",
7    "name_label": "Project"
8  }'

The response returns the updated custom field.

Create a custom field value

To create a value within a custom field, call the Create accounting field value API endpoint. Within a custom field, each value's external_id must be unique. Use the same external_id from your ERP on create and update so you can match records during sync.

Set accounting_field_id to the parent field id and send the create request with your ERP identifier as external_id:

Shell

1curl -X POST \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_field_values/create' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "request_id": "985461d5-016f-4e1f-a387-5f1380b42d92",
7    "accounting_field_id": "da66f0ff-8081-4db6-8333-4e011fe9561f",
8    "value": "PRJ-001",
9    "value_label": "Website Redesign | PRJ-001",
10    "external_id": "PRJ-001",
11    "legal_entity_ids": [
12      "le_U3jlHqQRNHWn2zAKeeT8sg"
13    ]
14  }'

Omit legal_entity_ids when it applies to all legal entities in your organization.

The response returns the created field value:

JSON

1{
2  "id": "ea76f0ff-8081-4db6-8333-4e011fe95620",
3  "accounting_field_id": "da66f0ff-8081-4db6-8333-4e011fe9561f",
4  "value": "PRJ-001",
5  "value_label": "Website Redesign | PRJ-001",
6  "external_id": "PRJ-001",
7  "legal_entity_ids": [
8    "le_U3jlHqQRNHWn2zAKeeT8sg"
9  ],
10  "status": "ACTIVE",
11  "created_at": "2026-06-15T00:00:00Z",
12  "updated_at": "2026-06-15T00:00:00Z"
13}

List custom field values

To retrieve values for a custom field, call the List accounting field values API endpoint.

Send the request with accounting_field_id and optional filters:

Shell

1curl -G \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_field_values' \
3  --data-urlencode 'accounting_field_id=da66f0ff-8081-4db6-8333-4e011fe9561f' \
4  --data-urlencode 'status=ACTIVE' \
5  --data-urlencode 'external_id=PRJ-001' \
6  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

The response returns a paginated list of field values:

JSON

1{
2  "items": [
3    {
4      "id": "ea76f0ff-8081-4db6-8333-4e011fe95620",
5      "accounting_field_id": "da66f0ff-8081-4db6-8333-4e011fe9561f",
6      "value": "PRJ-001",
7      "value_label": "Website Redesign | PRJ-001",
8      "external_id": "PRJ-001",
9      "legal_entity_ids": [
10        "le_U3jlHqQRNHWn2zAKeeT8sg"
11      ],
12      "status": "ACTIVE",
13      "created_at": "2026-06-15T00:00:00Z",
14      "updated_at": "2026-06-15T00:00:00Z"
15    }
16  ],
17  "page_after": "string",
18  "page_before": "string"
19}

Key query parameters include:

Parameter	Description
`accounting_field_id`	Filter by the parent accounting field ID.
`status`	Filter by `ACTIVE` or `ARCHIVED`.
`external_id`	Filter by the external ID from your ERP.
`legal_entity_id`	Filter by a specific legal entity ID.
`page`	A bookmark for pagination. Use the value from `page_after` or `page_before` in the previous response.

Get custom field value details

To retrieve a specific field value, call the Get accounting field value API endpoint.

Use the value id from the list or create response:

Shell

1curl -G \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_field_values/{{VALUE_ID}}' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}'

Update a custom field value

To update an existing field value, call the Update accounting field value API endpoint.

Send the update request. You must include accounting_field_id, status, and value on every update. Include any optional fields you want to change:

Shell

1curl -X POST \
2  'https://api-demo.airwallex.com/api/v1/accounting/accounting_field_values/{{VALUE_ID}}/update' \
3  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
4  -H 'Content-Type: application/json' \
5  -d '{
6    "accounting_field_id": "da66f0ff-8081-4db6-8333-4e011fe9561f",
7    "value": "PRJ-001",
8    "value_label": "Website Redesign | PRJ-001",
9    "external_id": "PRJ-001",
10    "legal_entity_ids": [
11      "le_U3jlHqQRNHWn2zAKeeT8sg"
12    ],
13    "status": "ARCHIVED"
14  }'

The response returns the updated field value:

JSON

1{
2  "id": "ea76f0ff-8081-4db6-8333-4e011fe95620",
3  "accounting_field_id": "da66f0ff-8081-4db6-8333-4e011fe9561f",
4  "value": "PRJ-001",
5  "value_label": "Website Redesign | PRJ-001",
6  "external_id": "PRJ-001",
7  "legal_entity_ids": [
8    "le_U3jlHqQRNHWn2zAKeeT8sg"
9  ],
10  "status": "ARCHIVED",
11  "created_at": "2026-06-15T00:00:00Z",
12  "updated_at": "2026-06-16T00:00:00Z"
13}

Use custom fields in Spend APIs

When coding line items on bills, purchase orders, expenses, or other Spend resources, reference a custom field value in accounting_field_selections using:

field_id: The custom field name (for example, Custom field 1). Do not use the display name (name_label).
field_value_id: The field value external_id (for example, PRJ-001)
identifier_type: EXTERNAL_ID

JSON

1{
2  "accounting_field_selections": [
3    {
4      "field_id": "Custom field 1",
5      "field_value_id": "PRJ-001",
6      "identifier_type": "EXTERNAL_ID"
7    }
8  ]
9}

Next steps

Now that you can manage custom fields via the API, explore these related guides:

Was this page helpful?