Entities Address Service

Back

Overview

The Entities Address Service manages addresses associated with entities (customers or suppliers). Addresses can be used for billing, shipping, or general contact purposes.

Each entity address includes:

• EntityID - identifier of the associated entity
• Name - address label or name
• Line1, Line2 - street address
• City, StateRegion, PostalCode, CountryCode - location data
• Phone, Email - contact information
• AddressType - address purpose: 0 = Default, 1 = Shipping, 2 = Billing (FK to entities.EntityAddressType)

Soft delete is supported — deleted addresses have IsDeleted = true and a DeletedAt timestamp rather than being physically removed.

All operations are tenant-aware and audited.

Endpoints

Back to Entities

GET

/api/v1/EntityAddresses/{id}

Returns a single address by its ID.

Route parameters:

• id (long, required) - address identifier

Behavior:

• Looks up the address by ID
• Returns 404 Not Found if the address does not exist

Response:

• AddressModel - address details

Authorization:

• Requires Bearer Token

GET

/api/v1/EntityAddresses/entity/{entityId}

Returns all addresses for a specific entity.

Route parameters:

• entityId (long, required) - entity identifier

Behavior:

• Filters addresses by EntityID
• Returns 404 Not Found if no addresses exist

Response:

• List<AddressModel> - all addresses for the entity

Authorization:

• Requires Bearer Token

POST

/api/v1/EntityAddresses

Creates a new entity address.

Request body (AddressModel):

• EntityID (long, required) - associated entity
• Name (string, required) - address name or label
• Line1 (string, required) - first line of address
• Line2 (string?, optional) - second line of address
• City (string, required)
• StateRegion (string?, optional)
• PostalCode (string, required)
• CountryCode (string, required)
• Phone (string?, optional)
• Email (string?, optional)
• AddressType (int?, optional, default: 0) - 0 = Default, 1 = Shipping, 2 = Billing

Behavior:

• Validates required fields using IsReadyToAdd()
• Adds the address to the database
• Writes an audit log entry on success

Response:

• 201 Created - AddressModel

Authorization:

• Requires Bearer Token
• Permission: FullManage

PUT

/api/v1/EntityAddresses/{id}

Updates an existing entity address.

Route parameters:

• id (long, required) - address identifier

Request body (AddressModel):

• Required for update: Id (set from route), Name
• Optional: Line1, Line2, City, StateRegion, PostalCode, CountryCode, Phone, Email, AddressType, EntityID

Behavior:

• Validates required fields using IsReadyToUpdate()
• Updates only the provided fields
• Writes an audit log entry on success

Response:

• 200 OK - AddressModel

Authorization:

• Requires Bearer Token
• Permission: FullManage

DELETE

/api/v1/EntityAddresses/{id}

Soft-deletes an entity address by its ID.

Route parameters:

• id (long, required) - address identifier

Behavior:

• Performs a soft delete — sets IsDeleted = true and DeletedAt to the current timestamp
• Record is retained in the database
• Writes an audit log entry on success

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

Notes

• Validation is enforced in the service layer (IsReadyToAdd() / IsReadyToUpdate())
• An entity can have multiple addresses with different AddressType values
• AddressType must be a valid value from EntityAddressType (0, 1, or 2)
• The previous IsBilling / IsShipping boolean fields have been replaced by the integer AddressType
• Tenant-aware operations ensure data isolation per tenant
• Internal errors are logged but not exposed to API consumers