Create a client
const url = 'https://api2.recruso.co.uk/v1/clients';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"clientName":"Northgate Foods Ltd","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","clientInvoiceType":"example","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","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,"dni":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","madeLiveOn":"2026-03-04T09:12:44","madeLiveBy":12,"madeLeadOn":"2026-01-22T11:45:00","madeLeadBy":12,"isFactoredClient":false,"factorNo":"F-20551","creditCheckedOrCleared":true,"clientBankCode":"example","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/clients \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "clientName": "Northgate Foods Ltd", "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", "clientInvoiceType": "example", "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", "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, "dni": 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", "madeLiveOn": "2026-03-04T09:12:44", "madeLiveBy": 12, "madeLeadOn": "2026-01-22T11:45:00", "madeLeadBy": 12, "isFactoredClient": false, "factorNo": "F-20551", "creditCheckedOrCleared": true, "clientBankCode": "example", "notes": "Invoices must quote the site purchase order number." }'Creates a live client under your own agency. A client is the company that engages the agency for workers and is the entity invoices are ultimately raised against.
clientName, branchId, address1, town, county, country, postCode, companyRegNumber, terms, invoiceTo and lineOfBusiness are required. vatRegNumber becomes required when vatYn is true. Every other field is optional and can be filled in later with UpdateClient.
branchId must be a branch the Recruso user behind your API app can access. A branch outside that set returns 400, not 403.
clientInvoiceType is the invoice type name, not an id; an unrecognised value returns 400 listing the accepted names. mediaSourceId, loggingHoursId and receivingHoursId are ids from your agency’s Recruitment sources, Logging hours and Receiving hours lookups, and an id that does not exist returns 400.
The client is created as a live client and a client status record is created alongside it. Prospective clients are created through CreateLead instead.
The agency is taken from your credentials, so ownerId on the request is ignored. On success the response carries the new clientId and a Location header pointing at GetClientById.
Access. Requires a client-credentials access token. Tokens issued through the interactive user login are rejected.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”The client to create.
object
The 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
6Your reference for the client’s signed terms of business.
Example
TOB-2026-0142The date the client’s terms of business were issued.
Example
2026-02-18The date the client’s terms of business expire.
Example
2028-02-17The 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 payment terms agreed with the client, as free text. Required, up to 50 characters.
Example
30 days from invoice dateThe 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.
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.ukFirst line of the address invoices are sent to, when it differs from the trading address.
Example
Finance Shared ServicesSecond line of the invoice address.
Example
PO Box 194Town or city of the invoice address.
Example
ManchesterCounty of the invoice address.
Example
Greater ManchesterCountry of the invoice address.
Example
United KingdomPostcode of the invoice address.
Example
M60 2LAThe email address invoices are sent to.
Example
accountspayable@example-northgate.co.ukThe name invoices are addressed to. Required, up to 50 characters.
Example
Accounts PayableWhether a purchase order number must be supplied before the client can be invoiced.
Example
trueThe logging hours that apply to this client, as an id from your agency’s Logging hours lookup.
Example
2The receiving hours that apply to this client, as an id from your agency’s Receiving hours lookup.
Example
3Free-text instructions to apply when invoicing the client. Up to 550 characters.
Example
One consolidated invoice per site, weekly.When the client was sent to Sage, in UK local time (GMT/BST).
Example
2026-03-05T08:30:00The Recruso user who sent the client to Sage.
Example
12The client’s account number in Sage. Up to 10 characters.
Example
NOR001The client’s line of business. Required, up to 100 characters.
Example
Food manufacturingWhen the client was made live, in UK local time (GMT/BST).
Example
2026-03-04T09:12:44The Recruso user who made the client live.
Example
12When the client was recorded as a lead, in UK local time (GMT/BST).
Example
2026-01-22T11:45:00The Recruso user who recorded the client as a lead.
Example
12Whether the client’s invoices are handled by an invoice factoring provider.
Example
falseThe client’s reference with the invoice factoring provider. Up to 15 characters.
Example
F-20551Whether the client has been credit checked or cleared for credit.
Example
trueFree-text notes about the client. Up to 2000 characters.
Example
Invoices must quote the site purchase order number.Responses
Section titled “Responses”Created
A newly created client.
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.
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, "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, "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"}