sn# Customer Service Back

Overview

The Customer Service manages customer entities in the system. Customers represent individual or corporate clients and are backed by the unified EntityModel.

Each customer includes:

• Id - unique identifier
• Code - unique customer code
• Name - customer name
• Email - contact email
• Phone - contact phone number
• IsActive - active status flag
• Extended profile fields: AccountManagerName, AccountManagerUserId, WebsiteURL, DOB, Anniversary, Notes
• Classification: StatusId, CurrencyId, VATNumber, CompanyHouseRef, LeadTimeDays
• Financial: RelatedEntityId, RelatedEntityRelationship, PaymentTermsDays, IsPayOnAccount, CreditLimit

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

All operations are tenant-aware.

Endpoints

Back to Entities

GET

/api/v1/Customers/{id}

Returns a customer by its ID.

Route parameters:

• id (long, required) - customer identifier

Behavior:

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

Response:

• EntityModel - customer details

Authorization:

• Requires Bearer Token

GET

/api/v1/Customers/code/{code}

Returns a customer by its code.

Route parameters:

• code (string, required) - customer code

Behavior:

• Looks up the customer by code
• Returns 404 Not Found if the customer does not exist

Response:

• EntityModel - customer details

Authorization:

• Requires Bearer Token

GET

/api/v1/Customers/email/{email}

Returns customers by email.

Route parameters:

• email (string, required) - customer email

Behavior:

• Searches customers by email
• Returns 404 Not Found if no matching customers exist

Response:

• List<EntityModel> - customers matching the email

Authorization:

• Requires Bearer Token

GET

/api/v1/Customers

Returns a paginated, filterable list of customers.

Query parameters (pagination):

• page (int, default: 1) - page number (1-based)
• pageSize (int, default: 20, max: 100) - items per page. Pass 0 to receive only totalCount with an empty items array
• sortBy (string, optional) - field to sort by: name, code, email
• sortDesc (bool, default: false) - sort descending

Query parameters (filters):

• search (string, optional) - search across name, code and email
• isActive (bool, optional) - filter by active status; omit for all
• entityCode (string, optional) - filter by exact customer code
• hasAccessToAllProducts (bool, optional) - filter to customers with access to all products (true only)
• relatedEntityId (long, optional) - filter by related entity ID

Response:

• PagedResponse<EntityModel>

Authorization:

• Requires Bearer Token

GET

/api/v1/Customers/{id}/files

Returns a paginated list of file attachments linked to a customer.

Route parameters:

• id (long, required) - customer identifier

Query parameters: see FileFilterRequest (standard pagination + search)

Response:

• PagedResponse<FileMetadataModel>

Authorization:

• Requires Bearer Token

POST

/api/v1/Customers

Creates a new customer.

Request body (EntityModel):

• Code (string, required) - customer code
• Name (string, required) - customer name
• Email (string?, optional)
• Phone (string?, optional)
• IsActive (bool?, optional, default: true)
• AccountManagerName (string?, optional)
• AccountManagerUserId (int?, optional)
• WebsiteURL (string?, optional)
• DOB (DateTime?, optional)
• Anniversary (DateTime?, optional)
• Notes (string?, optional)
• StatusId (int?, optional) - FK to EntityStatus
• CurrencyId (int?, optional) - FK to Currency
• VATNumber (string?, optional)
• CompanyHouseRef (string?, optional)
• LeadTimeDays (int?, optional)
• RelatedEntityId (long?, optional)
• RelatedEntityRelationship (string?, optional)
• PaymentTermsDays (int?, optional)
• IsPayOnAccount (bool?, optional)
• CreditLimit (decimal?, optional)

Behavior:

• Validates required fields in service layer
• Writes an audit log entry on success

Response:

• 201 Created - EntityModel

Authorization:

• Requires Bearer Token
• Permission: FullManage

POST

/api/v1/Customers/{id}/files/assign

Assigns one or more existing files to a customer.

Route parameters:

• id (long, required) - customer identifier

Request body (FileIdsRequest):

• FileIds (List, required)

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

PUT

/api/v1/Customers/{id}

Updates an existing customer. All EntityModel fields can be provided; Id is taken from the route.

Route parameters:

• id (long, required) - customer identifier

Behavior:

• Validates required fields in service layer
• Writes an audit log entry on success

Response:

• 200 OK - EntityModel

Authorization:

• Requires Bearer Token
• Permission: FullManage

DELETE

/api/v1/Customers/{id}

Soft-deletes a customer by ID.

Route parameters:

• id (long, required) - customer 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

DELETE

/api/v1/Customers/{id}/files/remove

Removes one or more file associations from a customer (does not delete the file itself).

Route parameters:

• id (long, required) - customer identifier

Request body (FileIdsRequest):

• FileIds (List, required)

Response:

• 204 No Content

Authorization:

• Requires Bearer Token
• Permission: FullManage

Notes

• Customers and suppliers share the same EntityModel and underlying data store; IsSupplier = false for customers
• StatusTitle (read-only), CurrencyCode (read-only), and CurrencySymbol (read-only) are resolved and returned on read operations
• Validation is enforced in the service layer, not via model attributes
• Email and Code are used for searching and uniqueness
• Tenant-aware operations ensure data isolation per tenant
• Internal errors are logged but not exposed to API consumers