Description

Overview

The Addresses API provides functionality for managing addresses for various entities (users, customers, companies). It supports:

Multiple address types (registration, actual, operational, correspondence, billing)
Primary address designation
Country and postal code validation
RBAC-based access control

Core Concepts

Address Types

Registration Address: Official registered address for legal purposes
Actual Address: Physical location where an entity is located
Operational Address: Where operations are conducted (multiple allowed)
Correspondence Address: Where mail should be sent
Billing Address: For invoices and financial documents

Record Types

Different entity types can have different address requirements:

Customer: All address types allowed
User: Only actual and correspondence addresses
Company: All address types allowed

API Endpoints

Create Address

POST /v1/addresses

Create a new address for an entity.

Request Body:

{
  "rec_id": "uuid",
  "rec_type": "customer",
  "type": "registration",
  "street": "Bahnhofstrasse",
  "number": "123",
  "additional": "Floor 4",
  "postal_code": "8001",
  "city": "Zürich",
  "state": "Zürich",
  "country": "CH",
  "is_primary": true
}

Get Address

GET /v1/addresses/{id}

Retrieve address details by ID.

Update Address

PUT /v1/addresses/{id}

Update an existing address.

Request Body:

{
  "street": "New Street",
  "number": "456",
  "postal_code": "8002",
  "city": "Zürich"
}

Delete Address

DELETE /v1/addresses/{id}

Delete an address.

List Addresses

GET /v1/addresses

List addresses with optional filtering.

Query Parameters:

rec_id: Filter by record ID
rec_type: Filter by record type
type: Filter by address type

Set Primary Address

PUT /v1/addresses/{id}/primary

Set an address as primary for its type.

Error Codes

Code	Description
addresses_m.not_found	Address not found
addresses_m.failed_to_create	Failed to create address
addresses_m.failed_to_get	Failed to retrieve address
addresses_m.failed_to_update	Failed to update address
addresses_m.failed_to_delete	Failed to delete address
addresses_m.failed_to_list	Failed to list addresses
addresses_m.invalid_type	Invalid address type
addresses_m.invalid_country_code	Invalid country code
addresses_m.invalid_postal_code	Invalid postal code format
addresses_m.duplicate_primary	Only one primary address allowed per type
addresses_m.failed_to_check_address	Failed to verify address uniqueness

Validation Rules

Postal Code

Minimum 3 characters
Maximum 10 characters
Alphanumeric with optional spaces and hyphens

Street

Required
Maximum 255 characters

City

Required
Maximum 100 characters

Country

Required
ISO 2-letter code
Must be valid country code

Security

RBAC permission required for all operations

Best Practices

Address Types
- Use appropriate address type for the purpose
- Set primary address when relevant
- Verify addresses when possible
Validation
- Always validate country codes
- Use correct postal code format
- Include building/apartment numbers
Security
- Follow principle of least privilege
- Audit address changes
- Validate user permissions

Description

On this page