Skip to content
Recruso API

List a client's sites

GET
/v1/clients/{clientId}/sites
curl --request GET \
  --url 'https://api2.recruso.co.uk/v1/clients/1/sites?siteName=Trafford&sortColumn=sitename&sortOrder=asc&pageNumber=1&pageSize=20' \
  --header 'Authorization: <Authorization>'

Returns a paged list of the active sites belonging to one of your own agency’s clients. Archived sites are excluded; read one by id with GetSiteById if you need to inspect it.

A clientId that does not exist, belongs to another agency, or sits under a branch the Recruso user behind your API app cannot access returns an empty page rather than 404 — the client is not looked up, only used to scope the query, and no site of a client outside those branches is ever returned.

siteName matches case-insensitively on any part of the name. Results are paged 20 per page by default. Sort with sortColumn (sitename, town, postcode, createdon or modifiedon) and sortOrder (asc or desc); an unrecognised sortColumn falls back to sitename rather than failing.

Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
clientId
required
integer format: int32

The clientId path parameter

Query Parameters

Section titled “Query Parameters”
siteName

Optional case-insensitive partial match on the site name.

string
nullable
Example
Trafford

Optional case-insensitive partial match on the site name.

sortColumn

Column to sort by: sitename, town, postcode, createdon or modifiedon. Defaults to sitename, and an unrecognised value falls back to sitename rather than failing.

string
nullable
Example
sitename

Column to sort by: sitename, town, postcode, createdon or modifiedon. Defaults to sitename, and an unrecognised value falls back to sitename rather than failing.

sortOrder

Sort direction: asc (the default) or desc.

string
nullable
Example
asc

Sort direction: asc (the default) or desc.

pageNumber

Page number, 1-based. Defaults to 1.

integer format: int32
Example
1

Page number, 1-based. Defaults to 1.

pageSize

Number of sites per page. Defaults to 20.

integer format: int32
Example
20

Number of sites per page. Defaults to 20.

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media typeapplication/json
object
data
Array<object>

One active site belonging to the client.

object
siteId

The site’s unique identifier, assigned by Recruso.

integer format: int32
clientId

The client this site belongs to.

integer format: int32
siteName

The site’s name. Required, up to 70 characters, and unique among the client’s active sites.

string
memo

Free-text notes about the site. Up to 550 characters.

string
nullable
gre
number format: float
nullable
grn
number format: float
nullable
address1

First line of the site address. Up to 150 characters.

string
nullable
address2

Second line of the site address. Up to 50 characters.

string
nullable
town

Town or city of the site address.

string
nullable
county

County of the site address.

string
nullable
postCode

Postcode of the site address.

string
nullable
telephone1

The site’s main telephone number.

string
nullable
telephone2

A second telephone number for the site.

string
nullable
email

The site’s main email address.

string
nullable
invoiceMethodId

How invoices for this site are delivered, as an id from the invoice methods vocabulary.

integer format: int16
nullable
useSiteAddressForInvoice

Whether invoices for this site use the site address rather than the client’s invoice address.

boolean
nullable
useSiteEmailForInvoice

Whether invoices for this site are sent to the site email rather than the client’s invoice email.

boolean
nullable
branchId

The branch this site is managed under.

integer format: int16
nullable
timesheetEmail

The address timesheets for this site are sent to.

string
nullable
isDeleted

Whether the site is archived. Always false here — this list returns active sites only.

boolean
nullable
createdBy

The Recruso user who created the site.

integer format: int16
nullable
createdOn

When the site was created, in UK local time (GMT/BST) — not UTC.

string format: date-time
nullable
modifiedBy

The Recruso user who last updated the site. Null until the site is first updated.

integer format: int16
nullable
modifiedOn

When the site was last updated, in UK local time (GMT/BST) — not UTC. Null until the site is first updated.

string format: date-time
nullable
siteArchivedBy

The Recruso user who archived the site. Null while the site is active.

integer format: int16
nullable
siteArchivedOn

When the site was archived, in UK local time (GMT/BST). Null while the site is active.

string format: date-time
nullable
siteRestoredBy

The Recruso user who last restored the site. Null if the site has never been archived.

integer format: int16
nullable
siteRestoredOn

When the site was last restored, in UK local time (GMT/BST). Null if the site has never been archived.

string format: date-time
nullable
pageNumber
integer format: int32
pageSize
integer format: int32
totalCount
integer format: int32
pageCount
integer format: int32
nextPage
string
nullable
previousPage
string
nullable
Example
{
  "data": [
    {
      "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",
      "postCode": "M17 1RU",
      "telephone1": "0161 872 4410",
      "telephone2": "0161 872 4411",
      "email": "trafford@example-northgate.co.uk",
      "invoiceMethodId": 1,
      "useSiteAddressForInvoice": true,
      "useSiteEmailForInvoice": false,
      "branchId": 4,
      "timesheetEmail": "timesheets@example-northgate.co.uk",
      "isDeleted": false,
      "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"
    }
  ]
}

401

Section titled “401”

Unauthorized

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

403

Section titled “403”

Forbidden

Media typeapplication/problem+json
object
type
string
nullable
title
string
nullable
status
integer format: int32
nullable
detail
string
nullable
instance
string
nullable
Examplegenerated
{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}