List clients
const url = 'https://api2.recruso.co.uk/v1/clients';const options = {method: 'GET', headers: {Authorization: '<Authorization>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api2.recruso.co.uk/v1/clients \ --header 'Authorization: <Authorization>'Returns a paged list of the live clients in your own agency. Leads are excluded; use ListLeads for those.
The list is narrowed to clients under the branches the Recruso user behind your API app can access; a client under any other branch is never returned, even when branchId names that branch.
Each entry is a summary rather than the full record — enough to identify and contact a client. Call GetClientById for one client’s complete details, or ListClientsWithSites when you also need each client’s sites.
clientName matches case-insensitively on any part of the name; branchId is an exact match. clientStatusType is a status name from the client status type vocabulary, and an unrecognised value returns 400 listing the accepted names.
Results are paged: 25 per page by default, capped at 100. pageNumber below 1 is treated as 1. Sort with sortColumn (clientname, createdon, modifiedon, town or postcode) and sortOrder (asc or desc).
Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”Page number (1-based). Defaults to 1.
Page number (1-based). Defaults to 1.
Number of records per page. Defaults to 25, capped at 100.
Number of records per page. Defaults to 25, capped at 100.
Optional case-insensitive partial match on ClientName.
Optional case-insensitive partial match on ClientName.
Optional exact match on BranchId.
Optional exact match on BranchId.
Optional client status type name filter (e.g. “Current”, “Dormant”). Resolved to ID internally via tblClientStatusTypes.
Optional client status type name filter (e.g. “Current”, “Dormant”). Resolved to ID internally via tblClientStatusTypes.
Column to sort by. Accepted values: clientname, createdon, modifiedon, town, postcode. Defaults to clientname.
Column to sort by. Accepted values: clientname, createdon, modifiedon, town, postcode. Defaults to clientname.
Sort direction: “asc” (default) or “desc”.
Sort direction: “asc” (default) or “desc”.
Responses
Section titled “Responses”OK
object
One client in a list of clients — a summary rather than the full record.
object
The client’s unique identifier, assigned by Recruso.
The client’s registered or trading name. Required, up to 100 characters.
The branch the client is managed under. Must be a branch the Recruso user behind your API app can access.
The recruitment source the client came from, as an id from your agency’s Recruitment sources lookup.
The client’s company registration number. Required, up to 20 characters.
Whether the client is VAT registered. When true, vatRegNumber is required.
The client’s VAT registration number. Required when vatYn is true.
The payment terms agreed with the client, as free text. Required, up to 50 characters.
The invoice type, given by name rather than by id. Must be one of the names published by the client invoice types vocabulary; an unrecognised name returns 400 listing the accepted values.
The client’s website.
First line of the client’s trading address. Required, up to 100 characters.
Second line of the client’s trading address.
Town or city of the client’s trading address. Required, up to 50 characters.
County of the client’s trading address. Required, up to 50 characters.
Country of the client’s trading address. Required, up to 50 characters.
Postcode of the client’s trading address. Required, up to 15 characters.
The client’s main telephone number.
The client’s main email address.
The client’s line of business. Required, up to 100 characters.
When the client was created, in UK local time (GMT/BST) — not UTC.
When the client was last updated, in UK local time (GMT/BST) — not UTC. Null until the client is first updated.
Example
{ "data": [ { "clientId": 137, "clientName": "Northgate Foods Ltd", "branchId": 4, "mediaSourceId": 6, "companyRegNumber": "08841972", "vatYn": true, "vatRegNumber": "GB 412 8853 07", "terms": "30 days from invoice date", "website": "https://www.example-northgate.co.uk", "address1": "Northgate House", "address2": "22 Ashburton Road West", "town": "Trafford Park", "county": "Greater Manchester", "country": "United Kingdom", "postCode": "M17 1RU", "telephone1": "0161 872 4400", "email": "operations@example-northgate.co.uk", "lineOfBusiness": "Food manufacturing", "createdOn": "2026-03-04T09:12:44", "modifiedOn": "2026-06-11T14:02:09" } ]}Bad Request
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}Unauthorized
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}Forbidden
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}