Description
Purpose and use
Addresses hold the postal, registered, operational, billing, and residence locations attached to the platform's business records — customers, personas, counterparties, signatories, and documents. They provide onboarding evidence, invoice delivery points, tax-residency context, screening context, and operational correspondence details.
Who uses this. Onboarding analysts, compliance officers, customer service, and finance operations work with address records when validating identity, preparing statements or invoices, and tracing where a legal entity operates.
How it works. Every address belongs to an owning record, identified by that record's reference and its record type (for example a customer or a signatory). An address type (registration, actual, operational, correspondence, or billing) says what the address is for, and a primary flag marks the main address for that combination. Each address also carries the country in ISO three-letter form and a content hash used to detect duplicates.
What users do. Capture addresses during onboarding, update stale details after the customer confirms them, mark one address as primary for its purpose, filter addresses by owning record or type, and list them for review.
Outcomes and side effects. A correct address improves screening, reporting, invoice delivery, and audit evidence. Every change is tied to the user who made it and should be reviewed alongside the related customer or counterparty record. All operations require an authenticated user and are gated by role-based access.
Related manuals: Customers, Counterparties, Payers, KYB.
Core concepts
Address types
| Type | Purpose |
|---|---|
| Registration | Official registered address for legal purposes |
| Actual | Physical location where the entity sits |
| Operational | Where operations are conducted |
| Correspondence | Where mail should be sent |
| Billing | For invoices and financial documents |
Owning record
Each address names the record it belongs to and that record's type. The record type is a free-form label the platform sets according to the owning module (for example customers or signatories) — there is no fixed list enforced here, so operators should follow the convention of the owning module rather than expect a validated set.
What the system stores
Alongside the address fields, each record keeps a content hash (to spot duplicates), an active flag, the created/modified user and timestamp, and optional metadata. The audit timestamp is the last-modified time.
Tasks
Add an address
POST /v1/addresses
Creates an address for an owning record. The request must identify the customer and the owning record it belongs to, the record type, the address type, and the core location fields (street, postal code, city, and a three-letter country code are required). The country must be a valid ISO three-letter code. The created address is returned in full, including its generated identifier and content hash.
View or list addresses
GET /v1/addresses/{id}
GET /v1/addresses
GET /v2/addresses
- Get one returns a single address by its identifier.
- List (v1) returns a plain list, optionally filtered by owning record, record type, or address type.
- List (v2) is the paginated, search-oriented listing: it accepts structured search fields (owning record, record type, address type, country, city, postal code, primary and active flags), sorting, and paging, and returns a result envelope with the page of records, the total, the unfiltered total, and whether more pages remain. Use v2 for operational grids.
Results are scoped by role — a caller sees only the addresses their permissions allow.
Update an address
PUT /v1/addresses/{id}
Changes the supplied fields of an existing address — any of street, number, additional line, postal code, city, state, country, address type, or the primary flag — and returns the updated address. A supplied country is re-validated as a three-letter code.
Set an address as primary
PUT /v1/addresses/{id}/primary
Marks the address as the primary one for its owning record and address type. Any address that was previously primary for the same record and type is demoted automatically — there is no error if one already existed, and no more than one primary per combination remains. The operation returns no content on success.
Delete an address
DELETE /v1/addresses/{id}
Permanently removes the address record — a hard removal, not a deactivation. Because addresses serve as onboarding and compliance evidence, prefer keeping an obsolete address (and simply not marking it primary) over deleting it, unless it was captured in error. The operation returns a standard confirmation message on success.
Common failures and what they mean
| Situation | What the operator sees | What to do |
|---|---|---|
| Not signed in | Authorization failure | Sign in with a valid session |
| No permission | Access denied | Confirm the role grants address access |
| Address not found | Not found | Verify the identifier |
| Missing required field | Invalid input | Provide customer, owning record, record type, address type, street, postal code, city, and country |
| Wrong country format | Invalid country code | Use a valid ISO three-letter code (e.g. CHE) |
Underlying message keys (for support triage) live in the module's localization catalogue; operators act on the business meaning above.
Handler: DeleteAccount. Deactivates the account (active=false). Deactivating an account that is already inactive requires the caller to hold the Internal role; otherwise the row is treated as not found and returns 404 Not Found. This check is enforced atomically inside the transaction via a row lock (SELECT ... FOR UPDATE). NOTE: handler responds 200 (apireply.Ok200), not 204. See task item about aligning status code.
Handler: CreateAddress. Returns the full address object (models.Address), including id, address_hash, active, created_by, modified_by, metadata.