Update a lead
const url = 'https://api2.recruso.co.uk/v1/leads/1';const options = { method: 'PUT', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"id":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","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 PUT \ --url https://api2.recruso.co.uk/v1/leads/1 \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "id": 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", "telephone2": "0161 872 4401", "fax": "0161 872 4402", "email": "operations@example-northgate.co.uk", "notes": "Invoices must quote the site purchase order number." }'Updates one lead in your own agency.
This is a full replacement, not a partial merge: every mutable field is written from the request, so a field you omit is set to null.
This endpoint does not convert a lead into a client. There is no field here that changes the record’s type, and none of the client-only fields — terms, invoicing, Sage — can be set through it.
A live client id returns 404; update it through UpdateClient. So does a lead belonging to another agency, or under a branch the Recruso user behind your API app cannot access. branchId must be a branch that user can access: moving a lead to any other branch returns 400, not 403.
modifiedBy and modifiedOn are set from your credentials and the current UK local time.
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”The id path parameter
Request Bodyrequired
Section titled “Request Bodyrequired”The replacement values for a lead. Every mutable field is written, so an omitted field is set to null.
object
The lead to update. Taken from the route; a value in the request body is ignored.
Example
137The client’s registered or trading name. Required, up to 100 characters.
Example
Northgate Foods LtdThe branch the client is managed under. Must be a branch the Recruso user behind your API app can access.
Example
4The recruitment source the client came from, as an id from your agency’s Recruitment sources lookup.
Example
6The client’s company registration number. Required, up to 20 characters.
Example
08841972Whether the client is VAT registered. When true, vatRegNumber is required.
Example
trueThe client’s VAT registration number. Required when vatYn is true.
Example
GB 412 8853 07The client’s website.
Example
https://www.example-northgate.co.ukFirst line of the client’s trading address. Required, up to 100 characters.
Example
Northgate HouseSecond line of the client’s trading address.
Example
22 Ashburton Road WestTown or city of the client’s trading address. Required, up to 50 characters.
Example
Trafford ParkCounty of the client’s trading address. Required, up to 50 characters.
Example
Greater ManchesterCountry of the client’s trading address. Required, up to 50 characters.
Example
United KingdomPostcode of the client’s trading address. Required, up to 15 characters.
Example
M17 1RUThe client’s main telephone number.
Example
0161 872 4400A second telephone number for the client.
Example
0161 872 4401The client’s fax number.
Example
0161 872 4402The client’s main email address.
Example
operations@example-northgate.co.ukFree-text notes about the client. Up to 2000 characters.
Example
Invoices must quote the site purchase order number.Responses
Section titled “Responses”OK
A lead as it stands after the update.
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.
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 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.
Free-text notes about the client. Up to 2000 characters.
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", "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", "notes": "Invoices must quote the site purchase order number."}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"}Not Found
object
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example"}