Requests and Responses

This guide explains the conventions used across all API endpoints. Following these conventions will ensure consistent integrations with Recruso CRM.

Pagination

Most GET endpoints that return lists are paginated.

Request Parameters

• pageNumber → The current page (default: 1).
• pageSize → Number of records per page (default: 20).

Example request:

GET /api/workers?pageNumber=2&pageSize=10

Response Structure

Paginated results use the following format:

{
  "data": [
    { "id": 101, "firstName": "Alice", "lastName": "Smith" },
    { "id": 102, "firstName": "Bob", "lastName": "Jones" }
  ],
  "pageNumber": 2,
  "pageSize": 10,
  "nextPage": "https://api.recruso.co.uk/api/workers?pageNumber=3&pageSize=10",
  "previousPage": "https://api.recruso.co.uk/api/workers?pageNumber=1&pageSize=10",
  "pageCount": 5,
  "totalRecordCount": 48
}

Notes

• nextPage is null if there are no further results.
• previousPage is null on the first page.
• pageCount is derived from total records / page size.

Error Handling

The API uses a consistent Problem Details format (RFC 7807) for error responses.

Example Error Response

{
  "status": 500,
  "title": "An unexpected error occurred.",
  "instance": "/api/bookings"
}

Fields

• status → HTTP status code.
• title → Short description of the error.
• instance → The request path where the error occurred.

Common Status Codes

• 400 → Bad request (validation errors, missing parameters).
• 401 → Unauthorized (missing/invalid JWT token).
• 403 → Forbidden (user does not have access to resource).
• 404 → Not found (resource does not exist).
• 500 → Internal server error.

Time Zone

• When running on Azure Web Apps, the API ensures that application logic runs in UK local time (GMT/BST depending on daylight savings).

Conventions

• For business logic (e.g., bookings, plans, invoices), the API internally respects the configured agency work week and UK time zone rules.

Summary

• Use pageNumber + pageSize for all list requests.
• Expect Problem Details JSON for errors.

👉 Next, see the Agencies for details on how agencies are managed.