Create a site
const url = 'https://api2.recruso.co.uk/v1/clients/1/sites';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"clientId":137,"siteName":"Trafford Park DC","memo":"Gatehouse sign-in required; ask for the shift supervisor.","gre":1,"grn":1,"address1":"Northgate House","address2":"22 Ashburton Road West","town":"Trafford Park","county":"Greater Manchester","country":"United Kingdom","postCode":"M17 1RU","telephone1":"0161 872 4410","telephone2":"0161 872 4411","fax":"0161 872 4412","email":"trafford@example-northgate.co.uk","invoiceMethodId":1,"useSiteAddressForInvoice":true,"useSiteEmailForInvoice":false,"branchId":4,"timesheetEmail":"timesheets@example-northgate.co.uk"}'};
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/1/sites \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "clientId": 137, "siteName": "Trafford Park DC", "memo": "Gatehouse sign-in required; ask for the shift supervisor.", "gre": 1, "grn": 1, "address1": "Northgate House", "address2": "22 Ashburton Road West", "town": "Trafford Park", "county": "Greater Manchester", "country": "United Kingdom", "postCode": "M17 1RU", "telephone1": "0161 872 4410", "telephone2": "0161 872 4411", "fax": "0161 872 4412", "email": "trafford@example-northgate.co.uk", "invoiceMethodId": 1, "useSiteAddressForInvoice": true, "useSiteEmailForInvoice": false, "branchId": 4, "timesheetEmail": "timesheets@example-northgate.co.uk" }'Creates a site under one of your own agency’s clients. A site is the location work is actually performed at, and it is what rates, bookings and plans hang off — not the client.
Only siteName is required; every other field is optional and can be filled in later with UpdateSite. clientId in the body must match the clientId in the route, otherwise the request returns 400.
siteName must be unique among that client’s active sites. A clash with an active site returns 400. A clash with an archived site returns 409 with that site’s siteId, because the database keeps the name reserved — restore the archived site with RestoreSite, or choose a different name. Note that this 409 body is not an RFC 7807 problem document; it carries siteId and message.
invoiceMethodId is an id from the invoice methods vocabulary; an id that does not exist returns 400. branchId is optional, and when given must be a branch the Recruso user behind your API app can access — any other branch returns 400, not 403.
A client that does not exist, belongs to another agency, or sits under a branch that user cannot access returns 404. On success the response carries the new siteId and a Location header pointing at GetSiteById.
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 clientId path parameter
Request Bodyrequired
Section titled “Request Bodyrequired”The site to create.
object
The client the site belongs to. Must match the client id in the route.
Example
137The site’s name. Required, up to 70 characters, and unique among the client’s active sites.
Example
Trafford Park DCFree-text notes about the site. Up to 550 characters.
Example
Gatehouse sign-in required; ask for the shift supervisor.First line of the site address. Up to 150 characters.
Example
Northgate HouseSecond line of the site address. Up to 50 characters.
Example
22 Ashburton Road WestTown or city of the site address.
Example
Trafford ParkCounty of the site address.
Example
Greater ManchesterCountry of the site address.
Example
United KingdomPostcode of the site address.
Example
M17 1RUThe site’s main telephone number.
Example
0161 872 4410A second telephone number for the site.
Example
0161 872 4411The site’s fax number.
Example
0161 872 4412The site’s main email address.
Example
trafford@example-northgate.co.ukHow invoices for this site are delivered, as an id from the invoice methods vocabulary.
Example
1Whether invoices for this site use the site address rather than the client’s invoice address.
Example
trueWhether invoices for this site are sent to the site email rather than the client’s invoice email.
Example
falseThe branch this site is managed under.
Example
4The address timesheets for this site are sent to.
Example
timesheets@example-northgate.co.ukResponses
Section titled “Responses”Created
A newly created site.
object
The site’s unique identifier, assigned by Recruso.
The client this site belongs to.
The site’s name. Required, up to 70 characters, and unique among the client’s active sites.
Free-text notes about the site. Up to 550 characters.
First line of the site address. Up to 150 characters.
Second line of the site address. Up to 50 characters.
Town or city of the site address.
County of the site address.
Country of the site address.
Postcode of the site address.
The site’s main telephone number.
A second telephone number for the site.
The site’s fax number.
The site’s main email address.
How invoices for this site are delivered, as an id from the invoice methods vocabulary.
Whether invoices for this site use the site address rather than the client’s invoice address.
Whether invoices for this site are sent to the site email rather than the client’s invoice email.
The branch this site is managed under.
The address timesheets for this site are sent to.
The Recruso user who created the site.
When the site was created, in UK local time (GMT/BST) — not UTC.
Example
{ "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", "country": "United Kingdom", "postCode": "M17 1RU", "telephone1": "0161 872 4410", "telephone2": "0161 872 4411", "fax": "0161 872 4412", "email": "trafford@example-northgate.co.uk", "invoiceMethodId": 1, "useSiteAddressForInvoice": true, "useSiteEmailForInvoice": false, "branchId": 4, "timesheetEmail": "timesheets@example-northgate.co.uk", "createdBy": 12, "createdOn": "2026-03-06T10:41:12"}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"}Conflict
Returned with 409 when a site name is already held by an archived site of the same client. Not an RFC 7807 problem document.
object
The archived site already holding this name. Restore it with RestoreSite, or choose a different name.
An explanation of the conflict, and what to do about it.
Example
{ "siteId": 512, "message": "A site with this name was previously archived for this client. To restore it, use the restore endpoint or choose a different name."}