List clients with their sites
const url = 'https://api2.recruso.co.uk/v1/clients/with-sites';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/with-sites \ --header 'Authorization: <Authorization>'Returns a paged list of the live clients in your own agency, each with its sites embedded. This is the call to make when mirroring the client and site structure into another system: one request gives you both levels instead of a ListSites call per client.
As with ListClients, only clients under the branches the Recruso user behind your API app can access are returned.
Paging applies to clients, not sites — a page of 25 carries 25 clients and all of their sites. The client entries carry more fields than ListClients, including the invoice address block.
Filtering, sorting and paging behave exactly as in ListClients: clientName is a case-insensitive partial match, branchId an exact match, and clientStatusType a status name that returns 400 when unrecognised. 25 per page by default, capped at 100.
Archived sites are excluded, so the site list mirrors what ListSites returns for each client. A client with no active sites still appears, with an empty sites array.
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
A Client with its associated Sites for the “Clients with Sites” view.
object
The client’s unique identifier, assigned by Recruso.
The client’s registered or trading name. Required, up to 100 characters.
The Recruso user the client is assigned to. Set to the user behind your API app when the client is created.
When the client record was created, in UK local time (GMT/BST). A legacy column carrying the same value as createdOn.
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.
Your reference for the client’s signed terms of business.
The date the client’s terms of business were issued.
The date the client’s terms of business expire.
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.
The Recruso user who created the client.
When the client was created, in UK local time (GMT/BST) — not UTC.
The Recruso user who last updated the client. Null until the client is first updated.
When the client was last updated, in UK local time (GMT/BST) — not UTC. Null until the client is first updated.
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.
A second telephone number for the client.
The client’s fax number.
The client’s main email address.
First line of the address invoices are sent to, when it differs from the trading address.
Second line of the invoice address.
Town or city of the invoice address.
County of the invoice address.
Country of the invoice address.
Postcode of the invoice address.
The email address invoices are sent to.
The name invoices are addressed to. Required, up to 50 characters.
Whether a purchase order number must be supplied before the client can be invoiced.
The logging hours that apply to this client, as an id from your agency’s Logging hours lookup.
The receiving hours that apply to this client, as an id from your agency’s Receiving hours lookup.
Free-text instructions to apply when invoicing the client. Up to 550 characters.
When the client was sent to Sage, in UK local time (GMT/BST).
The Recruso user who sent the client to Sage.
The client’s account number in Sage. Up to 10 characters.
The client’s line of business. Required, up to 100 characters.
Whether the client’s invoices are handled by an invoice factoring provider.
The client’s reference with the invoice factoring provider. Up to 15 characters.
Whether the client has been credit checked or cleared for credit.
The client’s active sites. Archived sites are excluded, so this is empty for a client whose sites have all been archived.
Lightweight Site DTO nested inside ClientWithSitesDto. Mirrors the existing SiteDto from Sites/List but is scoped to this slice.
object
The site’s unique identifier, assigned by Recruso.
The client this site belongs to.
The site’s name. Required, up to 70 characters, and unique among the client’s active sites.
Free-text notes about the site. Up to 550 characters.
First line of the site address. Up to 150 characters.
Second line of the site address. Up to 50 characters.
Town or city of the site address.
County of the site address.
Country of the site address.
Postcode of the site address.
The site’s main telephone number.
A second telephone number for the site.
The site’s fax number.
The site’s main email address.
How invoices for this site are delivered, as an id from the invoice methods vocabulary.
The branch this site is managed under.
The address timesheets for this site are sent to.
The Recruso user who created the site.
When the site was created, in UK local time (GMT/BST) — not UTC.
The Recruso user who last updated the site. Null until the site is first updated.
When the site was last updated, in UK local time (GMT/BST) — not UTC. Null until the site is first updated.
The Recruso user who archived the site. Null while the site is active.
When the site was archived, in UK local time (GMT/BST). Null while the site is active.
The Recruso user who last restored the site. Null if the site has never been archived.
When the site was last restored, in UK local time (GMT/BST). Null if the site has never been archived.
Example
{ "data": [ { "clientId": 137, "clientName": "Northgate Foods Ltd", "userId": 12, "createdDate": "2026-03-04T09:12:44", "branchId": 4, "mediaSourceId": 6, "tobReference": "TOB-2026-0142", "tobIssueDate": "2026-02-18", "tobExpiryDate": "2028-02-17", "companyRegNumber": "08841972", "vatYn": true, "vatRegNumber": "GB 412 8853 07", "terms": "30 days from invoice date", "website": "https://www.example-northgate.co.uk", "createdBy": 12, "createdOn": "2026-03-04T09:12:44", "modifiedBy": 12, "modifiedOn": "2026-06-11T14:02:09", "address1": "Northgate House", "address2": "22 Ashburton Road West", "town": "Trafford Park", "county": "Greater Manchester", "country": "United Kingdom", "postCode": "M17 1RU", "telephone1": "0161 872 4400", "telephone2": "0161 872 4401", "fax": "0161 872 4402", "email": "operations@example-northgate.co.uk", "invoiceAddress1": "Finance Shared Services", "invoiceAddress2": "PO Box 194", "invoiceTown": "Manchester", "invoiceCounty": "Greater Manchester", "invoiceCountry": "United Kingdom", "invoicePostCode": "M60 2LA", "invoiceEmail": "accountspayable@example-northgate.co.uk", "invoiceTo": "Accounts Payable", "orderNumberRequired": true, "loggingHoursId": 2, "receivingHoursId": 3, "specialInvoiceInstructions": "One consolidated invoice per site, weekly.", "dateSentToSage": "2026-03-05T08:30:00", "sentToSageBy": 12, "sageAccountNumber": "NOR001", "lineOfBusiness": "Food manufacturing", "isFactoredClient": false, "factorNo": "F-20551", "creditCheckedOrCleared": true, "sites": [ { "siteId": 512, "clientId": 137, "siteName": "Trafford Park DC", "memo": "Gatehouse sign-in required; ask for the shift supervisor.", "address1": "Northgate House", "address2": "22 Ashburton Road West", "town": "Trafford Park", "county": "Greater Manchester", "country": "United Kingdom", "postCode": "M17 1RU", "telephone1": "0161 872 4410", "telephone2": "0161 872 4411", "fax": "0161 872 4412", "email": "trafford@example-northgate.co.uk", "invoiceMethodId": 1, "branchId": 4, "timesheetEmail": "timesheets@example-northgate.co.uk", "createdBy": 12, "createdOn": "2026-03-06T10:41:12", "modifiedBy": 12, "modifiedOn": "2026-06-11T14:02:09", "siteArchivedBy": 12, "siteArchivedOn": "2026-07-01T16:20:00", "siteRestoredBy": 12, "siteRestoredOn": "2026-07-14T09:05:00" } ] } ]}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"}