Skip to content

Address Handling

Overview

Addresses are managed as independent objects within the system. This design allows users to decide whether or not to share their addresses with partners, providing flexibility and privacy control.

When an address is included in a person save request, it is saved separately with the additionalType home.

Info

All addresses, including the home address, can be created, updated, and deleted via the independent address API endpoints, giving clients full control over address management.

Address types

The additionalType property helps categorize addresses based on their purpose. The following types are supported:

additionalType description
home Main address of the person. Only one home address is allowed per person.
secondhome Secondary home address (Zweitwohnungsadresse)
(none) Addresses without an additional type are considered flexible. These can be used as invoice, billing, shipping addresses, etc.

Info

If no additionalType is specified, the address is treated as a general-purpose address, such as for invoices or shipping.

Address Creation and Updates

Home Address Management

  • A person can have only one home address.
  • The home address can be created or updated:
    • Either directly via the person API by including an address in the person request.
    • Or, independently via the address API endpoints, allowing full lifecycle management (create, update, delete).

Managing All Addresses

  • All addresses, regardless of type (home, secondhome, or general-purpose), can be managed independently.
  • Use the address API endpoints to:
    • Create new address objects.
    • Update existing addresses.
    • Delete addresses when they are no longer needed.

Get Person Response

  • When fetching a person’s details, the home address is included directly in the response payload.
  • This ensures clients always have easy access to the primary address information of a person.

Address Usage in Marketplace Orders

  • During marketplace transactions, the person’s address is copied into the order.
  • After the address has been copied into the order, any updates to the original address will not affect the order address.
  • This design ensures the integrity of historical order data, preserving the address details at the time of order creation.
  • The address in the order can be updated using PUT /orders/{orderNumber}/customer