Client

A Client is a company or organization that requests workers from an Agency. Clients are managed under a Branch, allowing agencies to organize operations geographically or by business unit.

🏢 Clients are the entities for which bookings, plans, and invoices are generated.

Overview

• Each client belongs to a single branch (and, therefore, a single agency).

• Clients can have multiple sites, which represent physical locations where work is performed.

• Client metadata includes:

  • Company name and contact info
  • Communication details
  • Billing and invoicing preferences

API Endpoints

1. List All Clients

Retrieve all clients belonging to the authenticated user's branch or agency.

GET /api/clients

Query Parameters

• pageNumber (optional) – page number for pagination
• pageSize (optional) – number of records per page

Response Example

{
  "data": [
    {
      "id": "1",
      "name": "Recruso Logistics Ltd",
      "branchId": "1",
      "email": "contact@recrusologistics.co.uk",
      "phone": "+44 845 051 1055",
      "createdOn": "2021-02-10T09:30:00Z"
    }
  ],
  "pageNumber": 1,
  "pageSize": 20,
  "nextPage": null,
  "previousPage": null,
  "pageCount": 1,
  "totalRecordCount": 1
}

2. Get Client by ID

Retrieve details of a single client.

GET /api/clients/{clientId}

Response Example

{
  "id": "1",
  "name": "Recruso Logistics Ltd",
  "branchId": "1",
  "email": "contact@recrusologistics.co.uk",
  "phone": "+44 845 051 1055",
  "billingAddress": "1 Industrial Way, Manchester, EC2 4AA",
  "createdOn": "2021-02-10T09:30:00Z"
}

3. Create a Client

Create a new client under a branch.

POST /api/clients

Request Body

{
  "name": "Recruso Logistics Ltd",
  "branchId": "1",
  "email": "contact@recrusologistics.co.uk",
  "phone": "+44 845 051 1055",
  "billingAddress": "1 Industrial Way, Manchester, EC2 4AA"
}

Response Example

{
  "id": "C002",
  "name": "Recruso Logistics Ltd",
  "branchId": "1",
  "email": "contact@recrusologistics.co.uk",
  "phone": "+44 845 051 1055",
  "billingAddress": "1 Industrial Way, Manchester, EC2 4AA",
  "createdOn": "2025-10-06T12:00:00Z"
}

4. Update a Client

Update client details.

PUT /api/clients/{clientId}

Request Body

{
  "name": "Recruso Logistics Ltd UK",
  "email": "support@recrusologistics.co.uk",
  "phone": "+44 845 051 1055",
  "billingAddress": "1 Industrial Way, Manchester, EC2 4AA"
}

Response Example

{
  "id": "C002",
  "name": "Recruso Logistics Ltd UK",
  "branchId": "1",
  "email": "support@recrusologistics.co.uk",
  "phone": "+44 845 051 1055",
  "billingAddress": "1 Industrial Way, Manchester, EC2 4AA",
  "updatedOn": "2025-10-06T12:45:00Z"
}

5. Delete a Client

Delete an existing client by ID.

DELETE /api/clients/{clientId}

Response Example

{
  "status": "success",
  "message": "Client deleted successfully."
}

Relationships

• Each client belongs to one branch.
• Each client can have multiple sites.
• Bookings, plans, and invoices are linked to a client through its sites.

Typical Usage

Scenario: A mobile app allows agency users to manage clients and assign sites for bookings.

Steps:

1. Call GET /api/clients to list all clients.
2. Use POST /api/clients to add a new client.
3. Call GET /api/clients/{clientId} to view client details.
4. Update client information with PUT /api/clients/{clientId}.
5. Remove a client with DELETE /api/clients/{clientId} if necessary.

👉 Next: Site — Learn how to manage client sites, their rules, rates, and worker assignments.