Clients

Creates a new client record in your account.

• Method: POST
  

• Endpoint: /clients
  

• Content-Type: application/json
  

Required Fields:

• firstname (string): Client's first name
  

• lastname (string): Client's last name
  

Optional Fields:

• email (string): Email address
  

• phone (string): Phone number
  

• mobile (string): Mobile phone number
  

• clientNumber (string): Your internal client reference number
  

• companyName (string): Company name
  

• companyRegistrationNumber (string): Company registration number
  

• address1 (string): First line of address
  

• address2 (string): Second line of address
  

• town (string): Town or city
  

• county (string): County or state
  

• postcode (string): Postal code or ZIP code
  

• username (string): Username for client portal access
  

• password (string): Password for client portal access
  

• archived (boolean): Whether the client is archived (default: false)
  

Success Response:

• Status: 200 OK
  

• Body: Complete client object including generated GUID
  

Retrieves a specific client by their unique identifier.

• Method: GET
  

• Endpoint: /clients/{guid}
  

Parameters:

• guid (required): The client's unique identifier in GUID format
  

Success Response:

• Status: 200 OK
  

• Body: Complete client object
  

Error Response:

• Status: 404 Not Found
  

• Body: "Client not found"
  

Retrieves all clients in your account with pagination support.

• Method: GET
  

• Endpoint: /clients
  

Query Parameters (Optional):

• page (integer): Page number starting from 1 (default: 1)
  

• pageSize (integer): Number of clients per page, between 1-100 (default: 100)
  

• archived (boolean): Filter by archived status - true for archived clients, false for non-archived clients
  

• includeArchived (boolean): When true, returns all clients regardless of archived status
  

Archive Filtering:
By default, the API returns only non-archived (active) clients. You can modify this behaviour using the filtering parameters:

• Default behaviour: Shows only active clients (archived=false)
  

• Show archived clients only: Use ?archived=true
  

• Show all clients: Use ?includeArchived=true
  

Example URLs:

• /clients - Returns first 100 active clients (default)
  

• /clients?page=2 - Returns second page of 100 active clients
  

• /clients?page=1&pageSize=50 - Returns first 50 active clients
  

• /clients?archived=true - Returns archived clients only
  

• /clients?archived=false - Returns active clients only (explicit)
  

• /clients?includeArchived=true - Returns all clients (both active and archived)
  

• /clients?page=2&pageSize=50&archived=true - Returns second page of 50 archived clients
  

• /clients?page=1&includeArchived=true - Returns first page of all clients
  

Success Response:

• Status: 200 OK
  

• Body: Paginated response with clients array and pagination metadata
  

Response Structure:

{
  "clients": [
    {
      "guid": "123e4567-e89b-12d3-a456-426614174000",
      "firstname": "John",
      "lastname": "Doe",
      "email": "john@example.com",
      "phone": "555-0123",
      "mobile": "555-0124",
      "clientNumber": "C001",
      "companyName": "Example Corp",
      "companyRegistrationNumber": "12345678",
      "address1": "123 Main St",
      "address2": "Suite 100",
      "town": "Anytown",
      "county": "State",
      "postcode": "12345",
      "username": "johndoe",
      "archived": false
    }
  ],
  "pagination": {
    "currentPage": 1,
    "pageSize": 100,
    "totalItems": 250,
    "totalPages": 3,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Pagination Fields:

• currentPage: The current page number
  

• pageSize: Number of items per page
  

• totalItems: Total number of clients in your account
  

• totalPages: Total number of pages available
  

• hasNextPage: Boolean indicating if there are more pages
  

• hasPreviousPage: Boolean indicating if there are previous pages
  

Error Responses:

• Status: 400 Bad Request
  

• Body: "Page must be a positive integer" (if page < 1)
  

• Body: "PageSize must be between 1 and 100" (if pageSize is invalid)
  

Updates an existing client record. Supports partial updates - only include fields you want to change.

• Method: PUT
  

• Endpoint: /clients/{guid}
  

• Content-Type: application/json
  

Parameters:

• guid (required): The client's unique identifier in GUID format
  

Updatable Fields:
Any of the fields from the Create Client endpoint can be updated. You only need to include the fields you want to change.

Field Validation:

• firstname: Cannot be empty if provided
  

• lastname: Cannot be empty if provided
  

Success Response:

• Status: 200 OK
  

• Body: Updated client object
  

Error Response:

• Status: 404 Not Found
  

• Body: "Client not found"