Branch

A Branch represents a physical office or operational unit of an Agency. Branches help agencies manage clients, workers, bookings, and other resources locally while still being part of the parent agency.

🏢 Each branch belongs to exactly one agency and inherits agency-level settings such as work week, holiday rules.

Overview

• Branches allow agencies to manage geographically distributed operations.
• Each branch can have multiple clients and workers associated with it.
• Branch metadata includes contact information, location, and operational details.
• Branches support full CRUD operations via the API.

API Endpoints

1. List All Branches

Retrieve all branches belonging to the authenticated user's agency.

GET /api/branches

Query Parameters

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

Response Example

{
  "data": [
    {
      "id": "1",
      "name": "Recruso London",
      "address": "10 Fleet Street, London, EC4Y 1AA",
      "phone": "08450 511 055",
      "email": "london@recruso.co.uk",
      "createdOn": "2020-05-12T08:00:00Z"
    }
  ],
  "pageNumber": 1,
  "pageSize": 20,
  "nextPage": null,
  "previousPage": null,
  "pageCount": 1,
  "totalRecordCount": 1
}

2. Get Branch by ID

Retrieve a single branch by its unique identifier.

GET /api/branches/{branchId}

Response Example

{
  "id": "1",
  "name": "Recruso London",
  "address": "10 Fleet Street, Manchester, EC4Y 1AA",
  "phone": "+44 845 051 1055",
  "email": "london@recruso.co.uk",
  "createdOn": "2020-05-12T08:00:00Z"
}

3. Create a Branch

Create a new branch under the authenticated user's agency.

POST /api/branches

Request Body

{
  "name": "Recruso London",
  "address": "25 King Street, London, M2 6AG",
  "phone": "+44 845 051 1055",
  "email": "london@recruso.co.uk"
}

Response Example

{
  "id": "2",
  "name": "Recruso London",
  "address": "25 King Street, London, M2 6AG",
  "phone": "+44 845 051 1055",
  "email": "manchester@recruso.co.uk",
  "createdOn": "2025-10-06T10:00:00Z"
}

4. Update a Branch

Update an existing branch.

PUT /api/branches/{branchId}

Request Body

{
  "name": "Recruso London HQ",
  "address": "25 King Street, Manchester, M2 6AG",
  "phone": "+44 845 051 1055",
  "email": "manchester@recruso.co.uk"
}

Response Example

{
  "id": "2",
  "name": "Recruso London HQ",
  "address": "25 King Street, Manchester, M2 6AG",
  "phone": "+44 845 051 1055",
  "email": "manchester@recruso.co.uk"
  "modifiedOn": "2025-10-06T11:15:00Z"
}

5. Delete a Branch

Delete an existing branch by ID.

DELETE /api/branches/{branchId}

Response Example

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

Relationships

• Each branch belongs to one agency.
• Each branch manages its own clients and has workers assigned.
• Branches act as a logical grouping for operations and reporting.

Typical Usage

Scenario: A web admin panel allows creating new branches for an agency and updating their details.

Steps:

1. Call POST /api/branches to create a new branch.
2. Use GET /api/branches to list all branches for display.
3. Call PUT /api/branches/{branchId} to update branch information.
4. Call DELETE /api/branches/{branchId} to remove a branch if required.

👉 Next: Clients — Learn how to manage clients under branches and agencies.