[Feature]: Support Structured Address Fields for Contacts & Additional Addresses (bexio API compliance)

[kaspernowak]

Question or Feature?

⚠️ Breaking Change: Structured Address Fields Required for Contacts & Additional Addresses

Background

This issue is prompted by an official email from bexio (June 2025), notifying all API users of an upcoming breaking change to the address structure.

Starting 08.12.2025, all contact and additional address endpoints will require structured address fields:

• street_name
• house_number
• address_addition

The legacy address field will be deprecated and rejected in request payloads after this date.

Excerpt from bexio's email:
“Starting 08.12.2025, all contact- and additional addresses must be created and edited with the structured address fields. The current address field won’t be accepted anymore by that time. ... Please make sure that you do not send the address field in the payload after 07.12.2025, otherwise the request will result in an error.”

📎 See bexio changelog for official documentation.

🔍 Affected Endpoints

Contacts

• Bulk Create Contacts
• Create Contact
• Edit Contact
• Fetch/List/Search Contacts

Additional Addresses

• Create Additional Address
• Edit Additional Address
• Fetch/List/Search Additional Addresses

✅ Address Field Migration: Status & Checklist

I already started working on Implementing this change, and the process is listed below.

DTOs

• Add street_name, house_number, address_addition properties
  Added to all relevant DTOs (CreateEditContactDTO, ContactDTO, CreateEditAdditionalAddressDTO, etc.).
• Deprecate address field in request DTOs
  Marked with @deprecated and runtime warnings; kept for backward compatibility until cutoff date.
• Update fromArray logic
  • Request DTOs: Fallback logic to populate street_name from address if needed (for backward compatibility).
  • Response DTOs: No fallback; fields are mapped exactly as returned by bexio.

Request Classes

• Use new structured fields in payloads
  Payloads now use street_name, house_number, address_addition.
• Ensure address is not sent (except for legacy support)
  address is only included for backward compatibility, with clear deprecation warning and cutoff date.

Response Handling

• Parse and expose structured fields
  All new fields are mapped in response DTOs.
• Preserve address field for backward compatibility
  address is exposed as-is, with no transformation.

Validation

• Warn if address is used
  Runtime deprecation warnings are triggered if address is set in DTOs.

Tests

• Replace/add tests for structured fields
  Update or add tests to either cover both legacy (address) and new structured fields or only new structured fields.

Documentation

• Update README and code comments to reflect the change
  Add migration notes, usage examples for new fields, and deprecation policy for address.

---

📅 Timeline

• Structured fields became available: June 2025
• address will be rejected after 07.12.2025

📎 References

• bexio API changelog
• Official bexio API breaking change email (June 2025):

Dear bexio API user,

We would like to inform you about an adjustment of our API, which is a breaking change.
Starting 08.12.2025, all contact- and additional addresses must be created and edited with the structured address fields. The current address field won’t be accepted anymore by that time.

This is being done in the context of a regulatory adjustment in the Swiss Payment Standards, which require the use of the structured form of recipient addresses when transferring payments and generating payslips with QR codes.

Specifically, the following Contact API v2 endpoints and fields are affected:

Marked the address field as deprecated and added the fields street_name, house_number, and address_addition to the request payload of the following endpoints:

Contacts:

• Bulk Create Contacts
• Create Contact
• Edit Contact

Additional Addresses:

• Create Additional Address
• Edit Additional Address

Added the same fields to the response body of the following Contact API v2 endpoints:

Contacts:

• Bulk Create Contacts
• Create Contact
• Edit Contact
• Fetch a List of Contacts
• Fetch a Contact
• Search Contacts

Additional Addresses:

• Create Additional Address
• Edit Additional Address
• Fetch a List of Additional Addresses
• Fetch an Additional Address
• Search Additional Addresses

The new structured address fields will be available in the beginning of June.

Please make sure that you do not send the address field in the payload after 07.12.2025, otherwise the request will result in an error.

Sincerely
Your bexio API team

⚠️ Impact

This is a breaking change for all consumers who use Create or Edit endpoints for contacts or additional addresses.
Action is required before 08.12.2025 to ensure continued compatibility with the Bexio API.

[kaspernowak]

@StanBarrows I can create a PR that closes this issue after the OAuth2 support PR is merged.
It is difficult for me to comfortably update the tests for the Contacts requests, as I don't fully understand how the fixtures are recorded/generated.
And I don't fully understand why there are ContactAdditionalAddresses and AdditionalAddresses requests, as it seems like they use the same endpoints.

[StanBarrows]

Hey @kaspernowak

Many thanks for this.

For the Fixtures take a look at Saloon.
https://docs.saloon.dev/the-basics/testing#recording-requests-fixtures

[kaspernowak]

@StanBarrows I will take a closer look at the fixtures documentation, thanks!
I see a lot of the existing tests failing when I test locally, is this expected? As in they need to be run from this github repo to be successful? Or should we expect that all tests should success locally when running composer test?

[kaspernowak]

@StanBarrows I have created a PR that fixes this here