Description

Purpose and use

Addresses keep normalized postal, registered, operational, billing, and residence locations for customers, personas, counterparties, and documents. They support onboarding evidence, invoice delivery, tax residency review, sanctions screening context, and operational correspondence.

Who uses this. Onboarding analysts, compliance officers, customer service, and finance operations use address records when validating identity, preparing statements or invoices, and tracing where a legal entity operates.

How it works. Each address belongs to a business record such as a customer, persona, payer, or counterparty. Address type and record type tell operations whether the address is a registered office, correspondence point, billing destination, residence, or another controlled purpose.

What users do. Users capture addresses during onboarding, update stale contact details after customer confirmation, filter addresses by country or record owner, and keep inactive addresses for history rather than losing evidence.

Outcomes and side effects. A valid address improves screening, reporting, invoice delivery, and audit evidence. Changes are tied to the user who made them and should be reviewed alongside the related customer or counterparty record.

Related manuals: Customers, Counterparties, Payers, KYB.

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

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

1. Address Types

   • Use appropriate address type for the purpose
   • Set primary address when relevant
   • Verify addresses when possible

2. Validation

   • Always validate country codes
   • Use correct postal code format
   • Include building/apartment numbers

3. Security

   • Follow principle of least privilege
   • Audit address changes
   • Validate user permissions