List leads

GET

/v1/leads

curl --request GET \
  --url https://api2.recruso.co.uk/v1/leads \
  --header 'Authorization: <Authorization>'

• Production

Returns a paged list of the leads in your own agency. Live clients are excluded; use ListClients for those.

The list is narrowed to leads under the branches the Recruso user behind your API app can access; a lead under any other branch is never returned.

clientName matches case-insensitively on any part of the name and branchId is an exact match. Unlike ListClients there is no status filter, because a lead has no client status to filter on.

Results are paged: 25 per page by default, capped at 100. 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

• Bearer

Parameters

Query Parameters

pageNumber

Page number (1-based). Defaults to 1.

integer format: int32

Page number (1-based). Defaults to 1.

pageSize

Number of records per page. Defaults to 25, capped at 100.

integer format: int32

Number of records per page. Defaults to 25, capped at 100.

clientName

Optional case-insensitive partial match on ClientName.

string

nullable

Optional case-insensitive partial match on ClientName.

branchId

Optional exact match on BranchId.

integer format: int16

nullable

Optional exact match on BranchId.

sortColumn

Column to sort by. Accepted values: clientname, createdon, modifiedon, town, postcode. Defaults to clientname.

string

nullable

Column to sort by. Accepted values: clientname, createdon, modifiedon, town, postcode. Defaults to clientname.

sortOrder

Sort direction: “asc” (default) or “desc”.

string

nullable

Sort direction: “asc” (default) or “desc”.

Responses

200

OK

Media typeapplication/json

object

data

Array<object>

One lead in a list of leads — a summary rather than the full record.

object

clientId

The client’s unique identifier, assigned by Recruso.

integer format: int32

clientName

The client’s registered or trading name. Required, up to 100 characters.

string

branchId

The branch the client is managed under. Must be a branch the Recruso user behind your API app can access.

integer format: int16

mediaSourceId

The recruitment source the client came from, as an id from your agency’s Recruitment sources lookup.

integer format: int16

nullable

companyRegNumber

The client’s company registration number. Required, up to 20 characters.

string

nullable

vatYn

Whether the client is VAT registered. When true, vatRegNumber is required.

boolean

nullable

vatRegNumber

The client’s VAT registration number. Required when vatYn is true.

string

nullable

website

The client’s website.

string

nullable

address1

First line of the client’s trading address. Required, up to 100 characters.

string

nullable

address2

Second line of the client’s trading address.

string

nullable

town

Town or city of the client’s trading address. Required, up to 50 characters.

string

nullable

county

County of the client’s trading address. Required, up to 50 characters.

string

nullable

country

Country of the client’s trading address. Required, up to 50 characters.

string

nullable

postCode

Postcode of the client’s trading address. Required, up to 15 characters.

string

nullable

telephone1

The client’s main telephone number.

string

nullable

email

The client’s main email address.

string

nullable

createdOn

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

string format: date-time

nullable

modifiedOn

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

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": [
    {
      "clientId": 137,
      "clientName": "Northgate Foods Ltd",
      "branchId": 4,
      "mediaSourceId": 6,
      "companyRegNumber": "08841972",
      "vatYn": true,
      "vatRegNumber": "GB 412 8853 07",
      "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",
      "createdOn": "2026-03-04T09:12:44",
      "modifiedOn": "2026-06-11T14:02:09"
    }
  ]
}

400

Bad Request

Media typeapplication/problem+json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

401

Unauthorized

Media typeapplication/problem+json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}

403

Forbidden

Media typeapplication/problem+json

object

type

string

nullable

title

string

nullable

status

integer format: int32

nullable

detail

string

nullable

instance

string

nullable

Example^generated

{
  "type": "example",
  "title": "example",
  "status": 1,
  "detail": "example",
  "instance": "example"
}