Beneficiary Tax Statements
A beneficiary tax statement is an annual 1099 form (1099-NEC or 1099-K) aggregating the taxable payments made to a recipient in a tax year, together with payer and recipient information. Use these APIs to retrieve statements, file them to the IRS, and download the rendered PDF.
Retrieve a Beneficiary Tax Statement
GET /api/v1/beneficiary_tax_statements/{id}
Retrieve the details of a specific beneficiary tax statement by its unique ID.
x-on-behalf-of headerUnique ID of the beneficiary tax statement.
Time when the tax statement was created, in ISO 8601 format.
Unique identifier of a recipient.
Unique ID of the tax statement.
Payer information.
A physical address used for tax reporting.
The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.
Country code (2-letter ISO 3166-1 alpha-2 country code).
Country name.
Postcode or zip code.
Name of state.
Name of city / suburb.
An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.
2-letter state code.
The person's name.
The person's phone number.
Taxpayer Identification Number (TIN) of the recipient.
The Tax Identification number.
Type of Tax Identification.
SSNSocial Security Number.
EINEmployer Identification Number.
ITINIndividual Taxpayer Identification Number.
QI_EINQualified Intermediary Employer Identification Number.
WP_EINWithholding Foreign Partnership Employer Identification Number.
WT_EINWithholding Foreign Trust Employer Identification Number.
Recipient information.
A physical address used for tax reporting.
The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.
Country code (2-letter ISO 3166-1 alpha-2 country code).
Country name.
Postcode or zip code.
Name of state.
Name of city / suburb.
An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.
2-letter state code.
The version of the tax profile used as the source of recipient information.
The person's name.
The person's phone number.
Taxpayer Identification Number (TIN) of the recipient.
The Tax Identification number.
Type of Tax Identification.
SSNSocial Security Number.
EINEmployer Identification Number.
ITINIndividual Taxpayer Identification Number.
QI_EINQualified Intermediary Employer Identification Number.
WP_EINWithholding Foreign Partnership Employer Identification Number.
WT_EINWithholding Foreign Trust Employer Identification Number.
Reason for rejection by the IRS. Present when the statement was rejected by the IRS after filing.
Status of the tax statement.
NOT_READYPayer or recipient details are incomplete. The statement is not ready to be filed
FILING_NOT_APPLICABLEFiling is not applicable (the recipient is non-US, or the taxable income is $0)
FILING_OPTIONALTax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold
FILING_REQUIREDTax statement is complete and taxable income meets the mandatory threshold
FILING_IN_PROGRESSThe filing process has started asynchronously in the background
FILEDThe statement has been filed to the IRS
ACCEPTEDThe statement has been accepted by the IRS
REJECTEDThe statement has been rejected by the IRS
EXPIREDThe statement has not been filed and expired after 2 years automatically
The tax year of this statement.
Total transfer amount submitted to the IRS, in US dollars.
The tax statement form type.
1099-NECForm 1099-NEC, reporting nonemployee compensation
1099-KForm 1099-K, reporting payment card and third-party network transactions
Time when the tax statement was last updated, in ISO 8601 format.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 404 | Possible errors: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements/txs-1a2b3c4d5e6f' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json'
1{2 "id": "txs-1a2b3c4d5e6f",3 "external_id": "recipient_98765",4 "tax_year": 2025,5 "type": "1099-NEC",6 "status": "FILING_REQUIRED",7 "payer_info": {8 "name": "Acme Corp",9 "address": {10 "address_line1": "123 Main Street",11 "address_line2": "Suite 400",12 "suburb": "San Francisco",13 "state": "California",14 "state_code": "CA",15 "postcode": "94105",16 "country_code": "US",17 "country_name": "United States"18 },19 "phone_number": "415-555-0100",20 "tax_identifier": {21 "type": "EIN",22 "number": "123456789"23 }24 },25 "recipient_info": {26 "name": "Jane Doe",27 "address": {28 "address_line1": "456 Oak Avenue",29 "suburb": "Austin",30 "state": "Texas",31 "state_code": "TX",32 "postcode": "78701",33 "country_code": "US",34 "country_name": "United States"35 },36 "phone_number": "512-555-0199",37 "tax_identifier": {38 "type": "SSN",39 "number": "987654321"40 },41 "beneficiary_tax_profile_version": 142 },43 "total_taxable_amount": 10000,44 "created_at": "2026-01-15T08:30:00+0000",45 "updated_at": "2026-02-03T14:22:45+0000"46}
List all Beneficiary Tax Statements
GET /api/v1/beneficiary_tax_statements
Retrieve a list of beneficiary tax statements, filtered by the supplied query parameters. Results are paginated using a cursor.
x-on-behalf-of headerFilter by beneficiary tax statement year.
Filter by the unique identifier of a recipient.
A bookmark for use in pagination to retrieve either the next page or the previous page of results.
To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call.
To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.
Number of results per page. Defaults to 100, minimum 10, maximum 200.
Filter by beneficiary tax statement status.
NOT_READYPayer or recipient details are incomplete. The statement is not ready to be filed
FILING_NOT_APPLICABLEFiling is not applicable (the recipient is non-US, or the taxable income is $0)
FILING_OPTIONALTax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold
FILING_REQUIREDTax statement is complete and taxable income meets the mandatory threshold
FILING_IN_PROGRESSThe filing process has started asynchronously in the background
FILEDThe statement has been filed to the IRS
ACCEPTEDThe statement has been accepted by the IRS
REJECTEDThe statement has been rejected by the IRS
EXPIREDThe statement has not been filed and expired after 2 years automatically
An array of paged results.
Unique identifier of a recipient.
Unique ID of the tax statement.
Status of the tax statement.
NOT_READYPayer or recipient details are incomplete. The statement is not ready to be filed
FILING_NOT_APPLICABLEFiling is not applicable (the recipient is non-US, or the taxable income is $0)
FILING_OPTIONALTax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold
FILING_REQUIREDTax statement is complete and taxable income meets the mandatory threshold
FILING_IN_PROGRESSThe filing process has started asynchronously in the background
FILEDThe statement has been filed to the IRS
ACCEPTEDThe statement has been accepted by the IRS
REJECTEDThe statement has been rejected by the IRS
EXPIREDThe statement has not been filed and expired after 2 years automatically
The tax year of this statement.
The tax statement form type.
1099-NECForm 1099-NEC, reporting nonemployee compensation
1099-KForm 1099-K, reporting payment card and third-party network transactions
Time when the tax statement was created, in ISO 8601 format.
Payer information.
A physical address used for tax reporting.
The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.
Country code (2-letter ISO 3166-1 alpha-2 country code).
Country name.
Postcode or zip code.
Name of state.
Name of city / suburb.
An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.
2-letter state code.
The person's name.
The person's phone number.
Taxpayer Identification Number (TIN) of the recipient.
The Tax Identification number.
Type of Tax Identification.
SSNSocial Security Number.
EINEmployer Identification Number.
ITINIndividual Taxpayer Identification Number.
QI_EINQualified Intermediary Employer Identification Number.
WP_EINWithholding Foreign Partnership Employer Identification Number.
WT_EINWithholding Foreign Trust Employer Identification Number.
Recipient information.
A physical address used for tax reporting.
The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.
Country code (2-letter ISO 3166-1 alpha-2 country code).
Country name.
Postcode or zip code.
Name of state.
Name of city / suburb.
An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.
2-letter state code.
The version of the tax profile used as the source of recipient information.
The person's name.
The person's phone number.
Taxpayer Identification Number (TIN) of the recipient.
The Tax Identification number.
Type of Tax Identification.
SSNSocial Security Number.
EINEmployer Identification Number.
ITINIndividual Taxpayer Identification Number.
QI_EINQualified Intermediary Employer Identification Number.
WP_EINWithholding Foreign Partnership Employer Identification Number.
WT_EINWithholding Foreign Trust Employer Identification Number.
Reason for rejection by the IRS. Present when the statement was rejected by the IRS after filing.
Total transfer amount submitted to the IRS, in US dollars.
Time when the tax statement was last updated, in ISO 8601 format.
The cursor for the next page of results. Pass this value as page in a subsequent request. null if there are no more results.
The cursor for the previous page of results. Pass this value as page in a subsequent request. null if there are no previous results.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "id": "txs-1a2b3c4d5e6f",5 "external_id": "recipient_98765",6 "tax_year": 2025,7 "type": "1099-NEC",8 "status": "FILING_REQUIRED",9 "recipient_info": {10 "name": "Jane Doe",11 "beneficiary_tax_profile_version": 112 },13 "total_taxable_amount": 10000,14 "created_at": "2026-01-15T08:30:00+0000",15 "updated_at": "2026-02-03T14:22:45+0000"16 }17 ],18 "page_before": "<string>",19 "page_after": "eyJwYWdlIjogMn0"20}
Submit a Beneficiary Tax Statement
POST /api/v1/beneficiary_tax_statements/{id}/submit
Submit the beneficiary tax statement to the IRS. The response contains the tax statement and its current filing status. This endpoint does not require a request body.
x-on-behalf-of headerUnique ID of the tax statement to file.
Time when the tax statement was created, in ISO 8601 format.
Unique identifier of a recipient.
Unique ID of the tax statement.
Payer information.
A physical address used for tax reporting.
The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.
Country code (2-letter ISO 3166-1 alpha-2 country code).
Country name.
Postcode or zip code.
Name of state.
Name of city / suburb.
An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.
2-letter state code.
The person's name.
The person's phone number.
Taxpayer Identification Number (TIN) of the recipient.
The Tax Identification number.
Type of Tax Identification.
SSNSocial Security Number.
EINEmployer Identification Number.
ITINIndividual Taxpayer Identification Number.
QI_EINQualified Intermediary Employer Identification Number.
WP_EINWithholding Foreign Partnership Employer Identification Number.
WT_EINWithholding Foreign Trust Employer Identification Number.
Recipient information.
A physical address used for tax reporting.
The first line of a physical address, typically including the street number and name of the building or residence. A P.O. box is not acceptable.
Country code (2-letter ISO 3166-1 alpha-2 country code).
Country name.
Postcode or zip code.
Name of state.
Name of city / suburb.
An optional field that can be used to capture additional information about the address, such as the apartment/suite number, or floor number.
2-letter state code.
The version of the tax profile used as the source of recipient information.
The person's name.
The person's phone number.
Taxpayer Identification Number (TIN) of the recipient.
The Tax Identification number.
Type of Tax Identification.
SSNSocial Security Number.
EINEmployer Identification Number.
ITINIndividual Taxpayer Identification Number.
QI_EINQualified Intermediary Employer Identification Number.
WP_EINWithholding Foreign Partnership Employer Identification Number.
WT_EINWithholding Foreign Trust Employer Identification Number.
Reason for rejection by the IRS. Present when the statement was rejected by the IRS after filing.
Status of the tax statement.
NOT_READYPayer or recipient details are incomplete. The statement is not ready to be filed
FILING_NOT_APPLICABLEFiling is not applicable (the recipient is non-US, or the taxable income is $0)
FILING_OPTIONALTax statement is complete and taxable income is greater than $0 but does not meet the mandatory threshold
FILING_REQUIREDTax statement is complete and taxable income meets the mandatory threshold
FILING_IN_PROGRESSThe filing process has started asynchronously in the background
FILEDThe statement has been filed to the IRS
ACCEPTEDThe statement has been accepted by the IRS
REJECTEDThe statement has been rejected by the IRS
EXPIREDThe statement has not been filed and expired after 2 years automatically
The tax year of this statement.
Total transfer amount submitted to the IRS, in US dollars.
The tax statement form type.
1099-NECForm 1099-NEC, reporting nonemployee compensation
1099-KForm 1099-K, reporting payment card and third-party network transactions
Time when the tax statement was last updated, in ISO 8601 format.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 404 | Possible errors: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements/txs-1a2b3c4d5e6f/submit' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json'
1{2 "id": "txs-1a2b3c4d5e6f",3 "external_id": "recipient_98765",4 "tax_year": 2025,5 "type": "1099-NEC",6 "status": "FILING_IN_PROGRESS",7 "recipient_info": {8 "name": "Jane Doe",9 "beneficiary_tax_profile_version": 110 },11 "total_taxable_amount": 1000012}
Download a Beneficiary Tax Statement
POST /api/v1/beneficiary_tax_statements/{id}/download
Generate the PDF of a beneficiary tax statement (the rendered 1099 form).
x-on-behalf-of headerUnique ID of the tax statement.
URL that can be used to retrieve the file. This URL expires shortly after it is generated.
Download URL expiry timestamp, in ISO 8601 format.
| Error status | Description |
|---|---|
| 400 | Possible errors: |
| 404 | Possible errors: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/beneficiary_tax_statements/txs-1a2b3c4d5e6f/download' \> --header 'Authorization: Bearer <token>'
1{2 "download_url": "https://api-downloads.airwallex.com/beneficiary_tax_statements/txs-1a2b3c4d5e6f.pdf?signature=1a2b3c4d5e6f7a8b9c0d",3 "expires_at": "2026-06-10T08:35:00+0000"4}