Create a site rate contract
const url = 'https://api2.recruso.co.uk/v1/clients/1/sites/1/rate-contracts';const options = { method: 'POST', headers: {Authorization: '<Authorization>', 'Content-Type': 'application/json'}, body: '{"siteId":512,"jobCategoryId":17,"shiftId":5,"jobDescription":"Order picking and pallet wrapping in a chilled environment.","otRulesAndDetails":"Time and a half after 40 hours in a week.","startTime":"2026-04-15T12:00:00Z","endTime":"2026-04-15T12:00:00Z","contactPersonId":88,"healthAndSafety":"Chilled store, 2-4C. Manual handling briefing required.","ppe":"Safety boots, hi-vis vest, thermal jacket.","assessmentRequired":true,"assessmentDetails":"Manual handling assessment at the gatehouse.","trainingRequired":true,"trainingDetails":"Half-day pallet truck training, renewed annually.","inductionRequired":true,"inductionDetails":"Site induction on first shift, 45 minutes.","holidayEntitlement":28,"agriculture":true,"expensesPaid":"Mileage at 45p per mile beyond 25 miles.","collectiveFacilities":"example","permanentVacancyAccess":"example","intervalOfPayments":"Weekly","lengthOfTermination":"1 week","frenchExtension":true,"isDailyRate":false,"dayRateRuleId":2,"breakTime":"30 minutes unpaid","restTimeBetweenShifts":11,"natureOfBusiness":"example","isRolledUpHoliday":false,"rolledUpHolidayOn":"2026-04-06T00:00:00","holidayPolicy":"Accrued at 12.07% of hours worked.","periodOfExtendedHire":"example","rates":[{"rateTypeId":1,"prePayRate":12.6,"preChargeRate":16.8,"preRequiredForHolidayPot":true,"prePayRateLimited":1,"prePayRatePsc":1,"preMarginRate":1,"preMarginRateLimited":1,"preMarginRatePsc":1,"preUseInAod":true,"postPayRate":13.4,"postChargeRate":17.65,"postRequiredForHolidayPot":true,"postPayRateLimited":1,"postPayRatePsc":1,"postMarginRate":1,"postMarginRateLimited":1,"postMarginRatePsc":1,"postUseInAod":true}]}'};
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/1/rate-contracts \ --header 'Authorization: <Authorization>' \ --header 'Content-Type: application/json' \ --data '{ "siteId": 512, "jobCategoryId": 17, "shiftId": 5, "jobDescription": "Order picking and pallet wrapping in a chilled environment.", "otRulesAndDetails": "Time and a half after 40 hours in a week.", "startTime": "2026-04-15T12:00:00Z", "endTime": "2026-04-15T12:00:00Z", "contactPersonId": 88, "healthAndSafety": "Chilled store, 2-4C. Manual handling briefing required.", "ppe": "Safety boots, hi-vis vest, thermal jacket.", "assessmentRequired": true, "assessmentDetails": "Manual handling assessment at the gatehouse.", "trainingRequired": true, "trainingDetails": "Half-day pallet truck training, renewed annually.", "inductionRequired": true, "inductionDetails": "Site induction on first shift, 45 minutes.", "holidayEntitlement": 28, "agriculture": true, "expensesPaid": "Mileage at 45p per mile beyond 25 miles.", "collectiveFacilities": "example", "permanentVacancyAccess": "example", "intervalOfPayments": "Weekly", "lengthOfTermination": "1 week", "frenchExtension": true, "isDailyRate": false, "dayRateRuleId": 2, "breakTime": "30 minutes unpaid", "restTimeBetweenShifts": 11, "natureOfBusiness": "example", "isRolledUpHoliday": false, "rolledUpHolidayOn": "2026-04-06T00:00:00", "holidayPolicy": "Accrued at 12.07% of hours worked.", "periodOfExtendedHire": "example", "rates": [ { "rateTypeId": 1, "prePayRate": 12.6, "preChargeRate": 16.8, "preRequiredForHolidayPot": true, "prePayRateLimited": 1, "prePayRatePsc": 1, "preMarginRate": 1, "preMarginRateLimited": 1, "preMarginRatePsc": 1, "preUseInAod": true, "postPayRate": 13.4, "postChargeRate": 17.65, "postRequiredForHolidayPot": true, "postPayRateLimited": 1, "postPayRatePsc": 1, "postMarginRate": 1, "postMarginRateLimited": 1, "postMarginRatePsc": 1, "postUseInAod": true } ] }'Creates a rate contract on one of your own agency’s sites. A rate contract binds a job category — optionally a shift — to the pay and charge rates for work done at that site, along with the assignment terms that go with it.
A contract holds one or more rate pairs. Each pair covers one rate type and carries both a pre-parity and a post-parity pay and charge rate — the rates before and after the worker qualifies for AWR parity. Both halves are always stored together; the API does not expose the duration field that distinguishes them.
jobCategoryId and at least one entry in rates are required, and siteId in the body must match the siteId in the route.
jobCategoryId, shiftId, dayRateRuleId and each rateTypeId must belong to your own agency; one that does not returns 400 naming the offending field. contactPersonId, if given, must be a contact of this same site.
Margin shortfalls are warnings, not errors. Where a rate type has a minimum margin configured, the contract is still created when a pair falls below it, and the response’s warnings array names the pair and the shortfall. Read warnings on a 201 — an empty array means every pair cleared its minimum.
isDailyRate is fixed at creation and cannot be changed later; when it is true, dayRateRuleId is required. The site must belong to the client named in the route, otherwise 404. On success the response carries the new siteRateContractId and a Location header pointing at GetSiteRateContractById.
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
The siteId path parameter
Request Bodyrequired
Section titled “Request Bodyrequired”The rate contract to create, with its rate pairs.
object
The site the contract applies to. Must match the site id in the route.
Example
512The job category this contract prices, as an id from your agency’s Job categories lookup. Required, and fixed at creation.
Example
17The shift this contract prices, as an id from your agency’s Shifts lookup. Fixed at creation.
Example
5The job description for work under this contract. Up to 5000 characters.
Example
Order picking and pallet wrapping in a chilled environment.The overtime rules that apply, as free text. Up to 500 characters.
Example
Time and a half after 40 hours in a week.The site contact responsible for this contract. Must be a contact of the same site.
Example
88Health and safety information for work under this contract. Up to 5000 characters.
Example
Chilled store, 2-4C. Manual handling briefing required.The personal protective equipment required for this work. Up to 5000 characters.
Example
Safety boots, hi-vis vest, thermal jacket.Whether a worker must complete an assessment before being placed under this contract.
Example
trueWhat the required assessment involves. Up to 5000 characters.
Example
Manual handling assessment at the gatehouse.Whether a worker must complete training before being placed under this contract.
Example
trueWhat the required training involves. Up to 5000 characters.
Example
Half-day pallet truck training, renewed annually.Whether a worker must complete an induction before being placed under this contract.
Example
trueWhat the required induction involves. Up to 5000 characters.
Example
Site induction on first shift, 45 minutes.The holiday entitlement for work under this contract.
Example
28What expenses are paid under this contract. Up to 5000 characters.
Example
Mileage at 45p per mile beyond 25 miles.How often workers are paid under this contract. Up to 50 characters.
Example
WeeklyThe notice required to end an assignment under this contract. Up to 50 characters.
Example
1 weekWhether the contract is priced at a daily rate rather than an hourly one. Fixed at creation, and requires dayRateRuleId when true.
Example
falseThe day rate rule that applies, as an id from your agency’s Day rate rules lookup. Required when isDailyRate is true.
Example
2The break time for work under this contract, as free text. Up to 25 characters.
Example
30 minutes unpaidThe rest time required between consecutive shifts.
Example
11Whether holiday pay is rolled up into the rate rather than accrued.
Example
falseWhen rolled-up holiday pay was turned on for this contract, in UK local time (GMT/BST).
Example
2026-04-06T00:00:00The holiday policy that applies to this contract. Up to 4000 characters.
Example
Accrued at 12.07% of hours worked.Rate pairs for this contract. At least one rate pair is required. Each rate pair includes pre-parity (Duration=0) and post-parity (Duration=12) rates for a specific rate type.
Represents a rate pair input (pre-parity and post-parity) for a specific rate type. Duration is handled internally and is not exposed to the API.
object
The rate type ID (FK to tblRateTypes in AgencySettings).
The hourly rate paid to the worker before they qualify for AWR parity.
Example
12.6The hourly rate charged to the client before the worker qualifies for AWR parity.
Example
16.8Whether the pre-parity rate contributes to the worker’s holiday pot.
Example
trueThe hourly rate paid to the worker once they qualify for AWR parity.
Example
13.4The hourly rate charged to the client once the worker qualifies for AWR parity.
Example
17.65Whether the post-parity rate contributes to the worker’s holiday pot.
Example
trueResponses
Section titled “Responses”Created
A newly created rate contract, with any advisory margin warnings.
object
The rate contract’s unique identifier, assigned by Recruso.
The site this rate contract applies to.
The job category this contract prices, as an id from your agency’s Job categories lookup. Required, and fixed at creation.
The shift this contract prices, as an id from your agency’s Shifts lookup. Fixed at creation.
The job description for work under this contract. Up to 5000 characters.
The overtime rules that apply, as free text. Up to 500 characters.
The site contact responsible for this contract. Must be a contact of the same site.
Health and safety information for work under this contract. Up to 5000 characters.
The personal protective equipment required for this work. Up to 5000 characters.
Whether a worker must complete an assessment before being placed under this contract.
What the required assessment involves. Up to 5000 characters.
Whether a worker must complete training before being placed under this contract.
What the required training involves. Up to 5000 characters.
Whether a worker must complete an induction before being placed under this contract.
What the required induction involves. Up to 5000 characters.
The holiday entitlement for work under this contract.
What expenses are paid under this contract. Up to 5000 characters.
How often workers are paid under this contract. Up to 50 characters.
The notice required to end an assignment under this contract. Up to 50 characters.
When the contract was last updated, in UK local time (GMT/BST) — not UTC. Null until the contract is first updated.
Whether the contract is deleted. Deleted contracts are excluded from the list but are still returned when fetched by id.
Whether the contract is priced at a daily rate rather than an hourly one. Fixed at creation, and requires dayRateRuleId when true.
The Recruso user who created the contract.
When the contract was created, in UK local time (GMT/BST) — not UTC.
The Recruso user who last updated the contract. Null until the contract is first updated.
The day rate rule that applies, as an id from your agency’s Day rate rules lookup. Required when isDailyRate is true.
The break time for work under this contract, as free text. Up to 25 characters.
The rest time required between consecutive shifts.
Whether holiday pay is rolled up into the rate rather than accrued.
When rolled-up holiday pay was turned on for this contract, in UK local time (GMT/BST).
The holiday policy that applies to this contract. Up to 4000 characters.
The rate pairs associated with this contract. Each entry groups pre-parity and post-parity rates for a specific rate type.
API response DTO for a site rate pair. Groups pre-parity (Duration=0) and post-parity (Duration=12) rates for a specific rate type. Duration is not exposed in the API.
object
The identifier of the pre-parity rate row in this pair.
The rate type this pair prices, as an id from your agency’s Rate types lookup.
The hourly rate paid to the worker before they qualify for AWR parity.
The hourly rate charged to the client before the worker qualifies for AWR parity.
Whether the pre-parity rate contributes to the worker’s holiday pot.
The identifier of the post-parity rate row in this pair.
The hourly rate paid to the worker once they qualify for AWR parity.
The hourly rate charged to the client once the worker qualifies for AWR parity.
Whether the post-parity rate contributes to the worker’s holiday pot.
Advisory warnings (e.g. margin rate below threshold). The record was saved successfully. Empty when there are no warnings.
Example
{ "siteRateContractId": 3041, "siteId": 512, "jobCategoryId": 17, "shiftId": 5, "jobDescription": "Order picking and pallet wrapping in a chilled environment.", "otRulesAndDetails": "Time and a half after 40 hours in a week.", "contactPersonId": 88, "healthAndSafety": "Chilled store, 2-4C. Manual handling briefing required.", "ppe": "Safety boots, hi-vis vest, thermal jacket.", "assessmentRequired": true, "assessmentDetails": "Manual handling assessment at the gatehouse.", "trainingRequired": true, "trainingDetails": "Half-day pallet truck training, renewed annually.", "inductionRequired": true, "inductionDetails": "Site induction on first shift, 45 minutes.", "holidayEntitlement": 28, "expensesPaid": "Mileage at 45p per mile beyond 25 miles.", "intervalOfPayments": "Weekly", "lengthOfTermination": "1 week", "modifiedOn": "2026-06-11T14:02:09", "isDeleted": false, "isDailyRate": false, "createdBy": 12, "createdOn": "2026-03-12T15:33:20", "modifiedBy": 12, "dayRateRuleId": 2, "breakTime": "30 minutes unpaid", "restTimeBetweenShifts": 11, "isRolledUpHoliday": false, "rolledUpHolidayOn": "2026-04-06T00:00:00", "holidayPolicy": "Accrued at 12.07% of hours worked.", "rates": [ { "siteRateId": 9107, "rateTypeId": 3, "prePayRate": 12.6, "preChargeRate": 16.8, "preRequiredForHolidayPot": true, "postSiteRateId": 9108, "postPayRate": 13.4, "postChargeRate": 17.65, "postRequiredForHolidayPot": true } ]}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"}