Create a lead

POST

/v1/leads

const url = 'https://api2.recruso.co.uk/v1/leads';
const options = {
  method: 'POST',
  headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'},
  body: '{"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","telephone2":"0161 872 4401","fax":"0161 872 4402","email":"operations@example-northgate.co.uk","notes":"Invoices must quote the site purchase order number."}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://api2.recruso.co.uk/v1/leads \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "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", "telephone2": "0161 872 4401", "fax": "0161 872 4402", "email": "operations@example-northgate.co.uk", "notes": "Invoices must quote the site purchase order number." }'

Creates a lead — a prospective client — under your own agency. A lead is the same kind of record as a client, held at an earlier stage, and it carries only the fields worth capturing before the relationship is agreed: name, branch, address, contact details and notes.

Only clientName and branchId are required, and vatRegNumber becomes required when vatYn is true. Billing terms, invoicing preferences and Sage details are not part of a lead — they arrive when the lead becomes a client.

branchId must be a branch the Recruso user behind your API app can access. A branch outside that set returns 400, not 403.

Leads and clients share one identifier space. A lead’s id is never reused as a client id, but a lead id sent to a client endpoint returns 404 rather than the record: the two are told apart by type, not by range.

mediaSourceId is an id from your agency’s Recruitment sources lookup; one that does not exist returns 400. On success the response carries the new clientId and a Location header pointing at GetLeadById.

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

Authorizations

Bearer

Request Body^required

application/json

The lead to create.

object

clientName

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

string

Example

Northgate Foods Ltd

branchId

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

integer format: int16

Example

mediaSourceId

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

integer format: int16

nullable

Invoices must quote the site purchase order number.

Responses

201

Created

application/json

A newly created lead.

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

userId

The Recruso user the client is assigned to. Set to the user behind your API app when the client is created.

integer format: int16

nullable

createdDate

When the client record was created, in UK local time (GMT/BST). A legacy column carrying the same value as createdOn.

string format: date-time

nullable

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

createdBy

The Recruso user who created the client.

integer format: int16

nullable

createdOn

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

string format: date-time

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

telephone2

A second telephone number for the client.

string

nullable

fax

The client’s fax number.

string

nullable

email

The client’s main email address.

string

nullable

notes

Free-text notes about the client. Up to 2000 characters.

string

nullable

Example

{
  "clientId": 137,
  "clientName": "Northgate Foods Ltd",
  "userId": 12,
  "createdDate": "2026-03-04T09:12:44",
  "branchId": 4,
  "mediaSourceId": 6,
  "companyRegNumber": "08841972",
  "vatYn": true,
  "vatRegNumber": "GB 412 8853 07",
  "website": "https://www.example-northgate.co.uk",
  "createdBy": 12,
  "createdOn": "2026-03-04T09:12:44",
  "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",
  "notes": "Invoices must quote the site purchase order number."
}

400

Bad Request

application/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

application/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

application/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"
}

Create a lead

Authorizations

Request Bodyrequired

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Responses

201

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated