{ "info": { "name": "Recruso API — 1.0.0", "description": "Production is the only environment an integrator can call; there is no sandbox, so every request in this collection acts on live agency data.\n\nSet `clientId` and `clientSecret`, run **Access → Issue an access token**, and the collection-level auth uses the token it stores for every other request.\n\nGenerated from openapi/v1.json by docs-site/scripts/generate-postman.mjs. Do not edit by hand.", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{accessToken}}", "type": "string" } ] }, "variable": [ { "key": "baseUrl", "value": "https://api2.recruso.co.uk", "type": "string" }, { "key": "clientId", "value": "", "type": "string" }, { "key": "clientSecret", "value": "", "type": "string" }, { "key": "accessToken", "value": "", "type": "string" } ], "item": [ { "name": "Agency setup", "description": "The agency itself and the structures underneath it: branches, and the cost centres each branch books work against.", "item": [ { "name": "Agencies", "item": [ { "name": "Get agency details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/agency", "host": [ "{{baseUrl}}" ], "path": [ "v1", "agency" ], "variable": [] }, "description": "Returns the configuration of the agency your credentials are bound to: contact details, the financial and holiday year, the working-week shape, and the AWR break thresholds. There is no agency identifier to pass — the agency is always your own.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update agency details", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/agency", "host": [ "{{baseUrl}}" ], "path": [ "v1", "agency" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"ownerName\": \"\",\n \"businessType\": \"\",\n \"address1\": \"\",\n \"address2\": \"\",\n \"postcode\": \"\",\n \"telephone1\": \"\",\n \"telephone2\": \"\",\n \"mobile\": \"\",\n \"fax\": \"\",\n \"email\": \"\",\n \"website\": \"\",\n \"vatNumber\": \"\",\n \"companyRegNumber\": \"\",\n \"endOfTaxYear\": \"2026-08-20T09:00:00\",\n \"yearStartDate\": \"2026-08-20T09:00:00\",\n \"weekEndingDateOfFirstWeek\": \"2026-08-20T09:00:00\",\n \"smsPurchased\": 0,\n \"customAccountNumber\": false,\n \"blockTimesheetAgreement\": \"\",\n \"firstDayOfWeek\": \"\",\n \"postCodeSearch\": false,\n \"subbyNameInPlan\": false,\n \"modifiedBy\": \"\",\n \"modifiedOn\": \"2026-08-20T09:00:00\",\n \"holidayAccrualMethodId\": 0,\n \"holidayYearStartDate\": \"2026-08-20T09:00:00\",\n \"holidayYearByWorkStartDate\": false,\n \"weeklyCappedHours\": 0,\n \"weeksToCalculateAveragePay\": 0,\n \"authorizedPassword\": \"\",\n \"town\": \"\",\n \"county\": \"\",\n \"country\": \"\",\n \"pageSize\": 0,\n \"sendSmsAs\": \"\",\n \"workerDefaultStatus\": 0,\n \"textMarketerUserName\": \"\",\n \"textMarketerPassword\": \"\",\n \"customSubContractorAccountNumber\": false,\n \"bankDetails\": \"\",\n \"healthAndSafety\": \"\",\n \"ppe\": \"\",\n \"assessmentDetails\": \"\",\n \"trainingDetails\": \"\",\n \"inductionDetails\": \"\",\n \"smsPerBranch\": false,\n \"pension\": 0,\n \"ssp\": 0,\n \"isRolledUpHoliday\": false,\n \"calculateVatOnRateType\": false,\n \"calculateVatOnClient\": false\n}" }, "description": "Updates the mutable settings of your own agency: trading name, contact details, the financial and holiday year start dates, the first day of the working week, and the weekly capped hours. Fields not listed on the request are left unchanged. There is no agency identifier to pass — the agency is always your own. Changing the year start dates or the first day of the week affects how future weeks are aligned; it does not restate weeks already worked.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "Branches", "item": [ { "name": "List branches", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches" ], "variable": [] }, "description": "Returns your agency's active branches, ordered by name. Deleted branches are excluded.\n\nThe list is further narrowed to the branches the Recruso user behind your API app can access, so it is not necessarily every branch in the agency. If a branch you expect is missing, check that user's branch access in the Recruso UI.\n\nThe response is not paged.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a branch", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"branchLocation\": \"Manchester Central\",\n \"address1\": \"Unit 7, Ashton House\",\n \"address2\": \"14 Deansgate\",\n \"town\": \"Manchester\",\n \"county\": \"Greater Manchester\",\n \"postcode\": \"M3 2BW\",\n \"country\": \"United Kingdom\",\n \"telephone1\": \"0161 496 0114\",\n \"telephone2\": \"0161 496 0115\",\n \"mobile\": \"07700 900432\",\n \"fax\": \"0161 496 0116\",\n \"email\": \"manchester@example-recruitment.co.uk\",\n \"website\": \"https://www.example-recruitment.co.uk\",\n \"sageDepartmentId\": 21,\n \"clientName\": \"\",\n \"agencyNameForEmail\": \"Example Recruitment (Manchester)\",\n \"displayInSelfRegistration\": true\n}" }, "description": "Creates a branch under your own agency. Only `branchLocation` is required; every other field is optional and may be filled in later with UpdateBranch.\n\n`branchLocation` must be unique across the agency's branches — a name that is already in use returns 400. A name belonging to a deleted branch is also rejected, because branches are only ever soft-deleted and a deleted branch keeps its name.\n\nThe agency is taken from your credentials, so there is no owner field on the request. The new branch is added to the accessible branches of the user behind your API app, so you can read it back straight away.\n\nOn success the response carries the new `branchId` and a `Location` header pointing at GetBranchById.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get branch details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single branch with its address, contact details, Sage department and self-registration settings.\n\nA branch belonging to another agency, one that has been deleted, or one outside your accessible-branch list all return 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a branch", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"branchLocation\": \"Manchester Central\",\n \"address1\": \"Unit 7, Ashton House\",\n \"address2\": \"14 Deansgate\",\n \"town\": \"Manchester\",\n \"county\": \"Greater Manchester\",\n \"postcode\": \"M3 2BW\",\n \"country\": \"United Kingdom\",\n \"telephone1\": \"0161 496 0114\",\n \"telephone2\": \"0161 496 0115\",\n \"mobile\": \"07700 900432\",\n \"fax\": \"0161 496 0116\",\n \"email\": \"manchester@example-recruitment.co.uk\",\n \"website\": \"https://www.example-recruitment.co.uk\",\n \"sageDepartmentId\": 21,\n \"clientName\": \"\",\n \"agencyNameForEmail\": \"Example Recruitment (Manchester)\",\n \"displayInSelfRegistration\": true\n}" }, "description": "Replaces the mutable details of a branch: name, address, contact details, Sage department, and the self-registration settings. This is a full replacement — a field omitted from the request is written as null, not left at its current value, so send the complete object.\n\n`branchLocation` is required and must stay unique across the agency's branches; a clash with another branch returns 400. Deleted branches keep their names, so a clash with one of those is rejected too. A branch outside your agency, already deleted, or not in your accessible-branch list returns 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a branch", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Soft-deletes a branch. The record is retained so historical data that references it stays intact; the branch simply stops appearing in ListBranches and GetBranchById.\n\nThere is no restore endpoint for branches, and the name stays taken — creating a branch with the same name afterwards is rejected. Cost centres under the branch are not deleted with it.\n\nA branch outside your agency, already deleted, or outside your accessible-branch list returns 404. Deleting is idempotent only in the sense that the second call returns 404, not 204.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "CostCentres", "item": [ { "name": "List a branch's cost centres", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:branchId/cost-centres", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":branchId", "cost-centres" ], "variable": [ { "key": "branchId", "value": "", "description": "Required." } ] }, "description": "Returns the active cost centres belonging to one branch. Deleted cost centres are excluded — use RestoreCostCentre to bring one back.\n\nCost centres are always scoped to a branch; there is no agency-wide list. A branch outside your agency or outside your accessible-branch list returns 404, and an accessible branch with no cost centres returns an empty array.\n\nThe response is not paged.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a cost centre", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:branchId/cost-centres", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":branchId", "cost-centres" ], "variable": [ { "key": "branchId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"branchId\": 4,\n \"costCentreName\": \"Warehouse Operatives\",\n \"sageDepartmentId\": 21,\n \"nominalCode\": 4001\n}" }, "description": "Creates a cost centre under a branch. Only `costCentreName` is required; `sageDepartmentId` and `nominalCode` are the optional accounting fields.\n\nThe name must be unique within the branch — the same name may be reused in a different branch. A clash with an active cost centre returns 400.\n\nA clash with a **deleted** cost centre returns 409 instead, because the underlying unique constraint covers deleted rows too. The 409 body carries the deleted record's `costCentreId`, so you can either call RestoreCostCentre on it or pick a different name.\n\nA branch outside your agency or outside your accessible-branch list returns 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get cost centre details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:branchId/cost-centres/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":branchId", "cost-centres", ":id" ], "variable": [ { "key": "branchId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single cost centre with its Sage department and nominal code.\n\nBoth ids must line up: a cost centre that exists but belongs to a different branch returns 404. A deleted cost centre, one outside your agency, or one under a branch you cannot access also returns 404 rather than 403.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a cost centre", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:branchId/cost-centres/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":branchId", "cost-centres", ":id" ], "variable": [ { "key": "branchId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"branchId\": 4,\n \"id\": 31,\n \"costCentreName\": \"Warehouse Operatives\",\n \"sageDepartmentId\": 21,\n \"nominalCode\": 4001\n}" }, "description": "Replaces the name and accounting fields of a cost centre. This is a full replacement — `sageDepartmentId` and `nominalCode` omitted from the request are written as null, so send the complete object.\n\nA cost centre cannot be moved between branches; `branchId` identifies it, it does not reassign it.\n\nThe new name must stay unique within the branch: a clash with another active cost centre returns 400, and a clash with a deleted one returns 409 carrying that record's `costCentreId`. A cost centre outside your agency, already deleted, or under a branch you cannot access returns 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a cost centre", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:branchId/cost-centres/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":branchId", "cost-centres", ":id" ], "variable": [ { "key": "branchId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"branchId\": 4,\n \"id\": 31\n}" }, "description": "Soft-deletes a cost centre. The record is retained so historical data that references it stays intact; it stops appearing in ListCostCentres and GetCostCentreById.\n\nThe name stays reserved within the branch, so creating a cost centre with the same name afterwards returns 409 rather than succeeding. RestoreCostCentre reverses this.\n\nA cost centre outside your agency, already deleted, under a different branch, or under a branch you cannot access returns 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Restore a deleted cost centre", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/branches/:branchId/cost-centres/:id/restore", "host": [ "{{baseUrl}}" ], "path": [ "v1", "branches", ":branchId", "cost-centres", ":id", "restore" ], "variable": [ { "key": "branchId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"branchId\": 4,\n \"id\": 31\n}" }, "description": "Reverses a soft delete, returning the cost centre to ListCostCentres and GetCostCentreById with its original name, Sage department and nominal code intact. There is no request body.\n\nThis is the resolution path for the 409 returned by CreateCostCentre and UpdateCostCentre: take the `costCentreId` from that response and call this endpoint with it.\n\nIf an active cost centre has since taken the same name in the branch, the restore returns 400 — rename or delete that one first. A cost centre that is not deleted, does not exist, is under a different branch, or is under a branch you cannot access returns 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] } ] }, { "name": "Clients & sites", "description": "Clients, the sites they operate, and everything hanging off a site — contact persons, rate contracts, activities and cost-centre links. Leads are prospective clients.", "item": [ { "name": "Clients", "item": [ { "name": "List clients", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients" ], "variable": [] }, "description": "Returns a paged list of the live clients in your own agency. Leads are excluded; use ListLeads for those.\n\nThe list is narrowed to clients under the branches the Recruso user behind your API app can access; a client under any other branch is never returned, even when `branchId` names that branch.\n\nEach entry is a summary rather than the full record — enough to identify and contact a client. Call GetClientById for one client's complete details, or ListClientsWithSites when you also need each client's sites.\n\n`clientName` matches case-insensitively on any part of the name; `branchId` is an exact match. `clientStatusType` is a status **name** from the client status type vocabulary, and an unrecognised value returns 400 listing the accepted names.\n\nResults are paged: 25 per page by default, capped at 100. `pageNumber` below 1 is treated as 1. Sort with `sortColumn` (`clientname`, `createdon`, `modifiedon`, `town` or `postcode`) and `sortOrder` (`asc` or `desc`).\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a client", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"clientName\": \"Northgate Foods Ltd\",\n \"branchId\": 4,\n \"mediaSourceId\": 6,\n \"tobReference\": \"TOB-2026-0142\",\n \"tobIssueDate\": \"2026-02-18\",\n \"tobExpiryDate\": \"2028-02-17\",\n \"companyRegNumber\": \"08841972\",\n \"vatYn\": true,\n \"vatRegNumber\": \"GB 412 8853 07\",\n \"terms\": \"30 days from invoice date\",\n \"clientInvoiceType\": \"\",\n \"website\": \"https://www.example-northgate.co.uk\",\n \"address1\": \"Northgate House\",\n \"address2\": \"22 Ashburton Road West\",\n \"town\": \"Trafford Park\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postCode\": \"M17 1RU\",\n \"telephone1\": \"0161 872 4400\",\n \"telephone2\": \"0161 872 4401\",\n \"fax\": \"0161 872 4402\",\n \"email\": \"operations@example-northgate.co.uk\",\n \"invoiceAddress1\": \"Finance Shared Services\",\n \"invoiceAddress2\": \"PO Box 194\",\n \"invoiceTown\": \"Manchester\",\n \"invoiceCounty\": \"Greater Manchester\",\n \"invoiceCountry\": \"United Kingdom\",\n \"invoicePostCode\": \"M60 2LA\",\n \"invoiceEmail\": \"accountspayable@example-northgate.co.uk\",\n \"invoiceTo\": \"Accounts Payable\",\n \"orderNumberRequired\": true,\n \"dni\": false,\n \"loggingHoursId\": 2,\n \"receivingHoursId\": 3,\n \"specialInvoiceInstructions\": \"One consolidated invoice per site, weekly.\",\n \"dateSentToSage\": \"2026-03-05T08:30:00\",\n \"sentToSageBy\": 12,\n \"sageAccountNumber\": \"NOR001\",\n \"lineOfBusiness\": \"Food manufacturing\",\n \"madeLiveOn\": \"2026-03-04T09:12:44\",\n \"madeLiveBy\": 12,\n \"madeLeadOn\": \"2026-01-22T11:45:00\",\n \"madeLeadBy\": 12,\n \"isFactoredClient\": false,\n \"factorNo\": \"F-20551\",\n \"creditCheckedOrCleared\": true,\n \"clientBankCode\": \"\",\n \"notes\": \"Invoices must quote the site purchase order number.\"\n}" }, "description": "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.\n\n`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.\n\n`branchId` must be a branch the Recruso user behind your API app can access. A branch outside that set returns 400, not 403.\n\n`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.\n\nThe client is created as a live client and a client status record is created alongside it. Prospective clients are created through CreateLead instead.\n\nThe 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.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get client details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns the full record for one live client in your own agency, including its trading and invoice addresses, billing terms and audit fields.\n\nOnly live clients are returned. A prospective client — a lead — returns 404 here even though the id exists; read it through GetLeadById instead. A client id belonging to another agency, or under a branch the Recruso user behind your API app cannot access, also returns 404, so existence is never disclosed.\n\n`clientInvoiceType` is resolved to its name; `mediaSourceId`, `loggingHoursId` and `receivingHoursId` are returned as raw lookup ids.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a client", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 137,\n \"clientName\": \"Northgate Foods Ltd\",\n \"branchId\": 4,\n \"mediaSourceId\": 6,\n \"tobReference\": \"TOB-2026-0142\",\n \"tobIssueDate\": \"2026-02-18\",\n \"tobExpiryDate\": \"2028-02-17\",\n \"companyRegNumber\": \"08841972\",\n \"vatYn\": true,\n \"vatRegNumber\": \"GB 412 8853 07\",\n \"terms\": \"30 days from invoice date\",\n \"clientInvoiceType\": \"\",\n \"website\": \"https://www.example-northgate.co.uk\",\n \"address1\": \"Northgate House\",\n \"address2\": \"22 Ashburton Road West\",\n \"town\": \"Trafford Park\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postCode\": \"M17 1RU\",\n \"telephone1\": \"0161 872 4400\",\n \"telephone2\": \"0161 872 4401\",\n \"fax\": \"0161 872 4402\",\n \"email\": \"operations@example-northgate.co.uk\",\n \"invoiceAddress1\": \"Finance Shared Services\",\n \"invoiceAddress2\": \"PO Box 194\",\n \"invoiceTown\": \"Manchester\",\n \"invoiceCounty\": \"Greater Manchester\",\n \"invoiceCountry\": \"United Kingdom\",\n \"invoicePostCode\": \"M60 2LA\",\n \"invoiceEmail\": \"accountspayable@example-northgate.co.uk\",\n \"invoiceTo\": \"Accounts Payable\",\n \"orderNumberRequired\": true,\n \"dni\": false,\n \"loggingHoursId\": 2,\n \"receivingHoursId\": 3,\n \"specialInvoiceInstructions\": \"One consolidated invoice per site, weekly.\",\n \"dateSentToSage\": \"2026-03-05T08:30:00\",\n \"sentToSageBy\": 12,\n \"sageAccountNumber\": \"NOR001\",\n \"lineOfBusiness\": \"Food manufacturing\",\n \"madeLiveOn\": \"2026-03-04T09:12:44\",\n \"madeLiveBy\": 12,\n \"madeLeadOn\": \"2026-01-22T11:45:00\",\n \"madeLeadBy\": 12,\n \"isFactoredClient\": false,\n \"factorNo\": \"F-20551\",\n \"creditCheckedOrCleared\": true,\n \"clientBankCode\": \"\",\n \"notes\": \"Invoices must quote the site purchase order number.\"\n}" }, "description": "Updates one live client in your own agency.\n\nThis 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. Send the complete record, not just the fields you are changing.\n\nThe same validation as CreateClient applies, and `clientInvoiceType` is again the invoice type name rather than an id. A lookup id that does not exist returns 400.\n\nA lead id returns 404 — leads are updated through UpdateLead. A client id belonging to another agency, or under a branch the Recruso user behind your API app cannot access, also returns 404. `branchId` must be a branch that user can access: moving a client to any other branch returns 400, not 403.\n\n`modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time; they are not taken from the request.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a client", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one live client in your own agency, together with its client status records.\n\nUnlike sites and site contacts, a client is **not** soft-deleted and there is no restore. The row is removed, so the delete only succeeds for a client nothing else references.\n\nA client that still has related records — sites, cost centres or bookings — cannot be deleted and returns 400. Remove or reassign those first.\n\nA lead id returns 404; delete leads through DeleteLead. A client id belonging to another agency, or under a branch the Recruso user behind your API app cannot access, also returns 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "List clients with their sites", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/with-sites", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", "with-sites" ], "variable": [] }, "description": "Returns a paged list of the live clients in your own agency, each with its sites embedded. This is the call to make when mirroring the client and site structure into another system: one request gives you both levels instead of a ListSites call per client.\n\nAs with ListClients, only clients under the branches the Recruso user behind your API app can access are returned.\n\nPaging applies to **clients**, not sites — a page of 25 carries 25 clients and all of their sites. The client entries carry more fields than ListClients, including the invoice address block.\n\nFiltering, sorting and paging behave exactly as in ListClients: `clientName` is a case-insensitive partial match, `branchId` an exact match, and `clientStatusType` a status name that returns 400 when unrecognised. 25 per page by default, capped at 100.\n\nArchived sites are **excluded**, so the site list mirrors what ListSites returns for each client. A client with no active sites still appears, with an empty `sites` array.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "Leads", "item": [ { "name": "List leads", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/leads", "host": [ "{{baseUrl}}" ], "path": [ "v1", "leads" ], "variable": [] }, "description": "Returns a paged list of the leads in your own agency. Live clients are excluded; use ListClients for those.\n\nThe list is narrowed to leads under the branches the Recruso user behind your API app can access; a lead under any other branch is never returned.\n\n`clientName` matches case-insensitively on any part of the name and `branchId` is an exact match. Unlike ListClients there is no status filter, because a lead has no client status to filter on.\n\nResults are paged: 25 per page by default, capped at 100. Sort with `sortColumn` (`clientname`, `createdon`, `modifiedon`, `town` or `postcode`) and `sortOrder` (`asc` or `desc`).\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a lead", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/leads", "host": [ "{{baseUrl}}" ], "path": [ "v1", "leads" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"clientName\": \"Northgate Foods Ltd\",\n \"branchId\": 4,\n \"mediaSourceId\": 6,\n \"companyRegNumber\": \"08841972\",\n \"vatYn\": true,\n \"vatRegNumber\": \"GB 412 8853 07\",\n \"website\": \"https://www.example-northgate.co.uk\",\n \"address1\": \"Northgate House\",\n \"address2\": \"22 Ashburton Road West\",\n \"town\": \"Trafford Park\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postCode\": \"M17 1RU\",\n \"telephone1\": \"0161 872 4400\",\n \"telephone2\": \"0161 872 4401\",\n \"fax\": \"0161 872 4402\",\n \"email\": \"operations@example-northgate.co.uk\",\n \"notes\": \"Invoices must quote the site purchase order number.\"\n}" }, "description": "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.\n\nOnly `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.\n\n`branchId` must be a branch the Recruso user behind your API app can access. A branch outside that set returns 400, not 403.\n\nLeads 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.\n\n`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.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get lead details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/leads/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "leads", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns the full record for one lead in your own agency.\n\nOnly prospective clients are returned. A live client returns 404 here even though the id exists; read it through GetClientById instead. A lead belonging to another agency, or under a branch the Recruso user behind your API app cannot access, also returns 404, so existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a lead", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/leads/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "leads", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 137,\n \"clientName\": \"Northgate Foods Ltd\",\n \"branchId\": 4,\n \"mediaSourceId\": 6,\n \"companyRegNumber\": \"08841972\",\n \"vatYn\": true,\n \"vatRegNumber\": \"GB 412 8853 07\",\n \"website\": \"https://www.example-northgate.co.uk\",\n \"address1\": \"Northgate House\",\n \"address2\": \"22 Ashburton Road West\",\n \"town\": \"Trafford Park\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postCode\": \"M17 1RU\",\n \"telephone1\": \"0161 872 4400\",\n \"telephone2\": \"0161 872 4401\",\n \"fax\": \"0161 872 4402\",\n \"email\": \"operations@example-northgate.co.uk\",\n \"notes\": \"Invoices must quote the site purchase order number.\"\n}" }, "description": "Updates one lead in your own agency.\n\nThis 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.\n\n**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.\n\nA 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.\n\n`modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a lead", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/leads/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "leads", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one lead in your own agency, together with its client status records.\n\nAs with a client, this is **not** a soft delete and there is no restore. The row is removed, so the delete only succeeds for a lead nothing else references.\n\nA lead that still has related records — sites, cost centres or bookings — cannot be deleted and returns 400.\n\nA live client id returns 404; delete it through DeleteClient. So does a lead belonging to another agency, or under a branch the Recruso user behind your API app cannot access.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "SiteActivities", "item": [ { "name": "List a site contact's activities", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/activities", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "activities" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." } ] }, "description": "Returns a paged list of the activities logged against one contact at one of your own agency's sites — the contact history for that person.\n\nThere are no filters or sort options; the contact's activities come back a page at a time.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Log an activity against a site contact", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/activities", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "activities" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"activityDate\": \"2026-05-14T10:30:00\",\n \"description\": \"Called to confirm cover for the bank holiday weekend.\",\n \"actionTaken\": \"Agreed 6 pickers for Saturday, confirmed by email.\",\n \"nextCallDate\": \"2026-05-21T09:00:00\",\n \"lastVisited\": \"2026-05-02T13:15:00\",\n \"activityTypeId\": 4,\n \"eventId\": \"cal-2026-05-14-0930\"\n}" }, "description": "Records an activity — a call, a visit, an email — against a contact at one of your own agency's sites. Activities are the contact history behind a site: what was discussed, what was agreed, and when to follow up.\n\nOnly `activityDate` is required. `activityTypeId`, when given, must belong to your agency's Activity types lookup; one that does not returns 400.\n\n`eventId` is accepted here and **cannot be changed afterwards** — it is absent from UpdateSiteActivity. Set it on creation or not at all.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\nOn success the response carries the new `siteActivityId` and a `Location` header pointing at GetSiteActivityById.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get site activity details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "activities", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one activity logged against a contact at one of your own agency's sites, including its follow-up dates and audit fields.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\nThe activity must also belong to the contact in the route.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a site activity", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "activities", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"activityDate\": \"2026-05-14T10:30:00\",\n \"description\": \"Called to confirm cover for the bank holiday weekend.\",\n \"actionTaken\": \"Agreed 6 pickers for Saturday, confirmed by email.\",\n \"nextCallDate\": \"2026-05-21T09:00:00\",\n \"lastVisited\": \"2026-05-02T13:15:00\",\n \"activityTypeId\": 4\n}" }, "description": "Updates one activity logged against a contact at one of your own agency's sites.\n\nThis 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.\n\n`eventId` cannot be changed — it is not part of this request, and an activity keeps whatever it was created with. An activity also cannot be moved to another contact.\n\n`activityTypeId`, when given, must belong to your agency's Activity types lookup; one that does not returns 400.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a site activity", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "activities", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Deletes one activity logged against a contact at one of your own agency's sites.\n\nThis is a **hard delete** — the row is removed. Unlike a site or a site contact, an activity is not retained and there is no restore, so the contact history loses the entry permanently.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\nThe activity must also belong to the contact in the route.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "SiteContactCostCentres", "item": [ { "name": "List a site contact's cost centres", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/cost-centres", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "cost-centres" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." } ] }, "description": "Returns every cost centre linked to one contact at one of your own agency's sites.\n\nThis list is **not paged** and takes no filters. Each entry carries the link's own id, which is what RemoveSiteContactCostCentre takes, not the cost centre id.\n\nThe list carries ids only. Read the cost centres themselves through the branch's cost centre endpoints for their names and details.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Link a cost centre to a site contact", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/cost-centres", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "cost-centres" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"costCentreId\": 19\n}" }, "description": "Links one of your agency's cost centres to a contact at a site, narrowing which cost centres that person's work is booked against. This is the contact-level counterpart to AddSiteCostCentre.\n\n**The cost centre must belong to the same branch as the site**, exactly as for a site link: a cross-branch link returns 400, and a site with no branch assigned cannot be linked at all.\n\nA cost centre already linked to the contact returns 400 rather than creating a duplicate, and a cost centre that does not exist returns 400.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\nOn success the `Location` header points at ListSiteContactCostCentres, since a single link has no endpoint of its own.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Unlink a cost centre from a site contact", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:contactPersonId/cost-centres/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":contactPersonId", "cost-centres", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "contactPersonId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes the link between a cost centre and a contact at one of your own agency's sites. Neither the cost centre nor the contact is touched; only the link is deleted.\n\nThe `id` in the route is the **link's** id — the `contactPersonCostCentreId` from ListSiteContactCostCentres — not the cost centre id.\n\nThis is a hard delete and there is no restore; re-link with AddSiteContactCostCentre if it was removed in error.\n\nThe client, site and contact in the route must line up — the site must belong to the client and the contact to the site — and any mismatch returns 404 rather than 403.\n\nThe link must also belong to the contact in the route.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "SiteContactPersons", "item": [ { "name": "List a site's contacts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." } ] }, "description": "Returns a paged list of the **active** contact persons on one of your own agency's sites. Deleted contacts are excluded and cannot be read back except through RestoreSiteContactPerson.\n\nThere are no filters or sort options — the whole contact list for the site comes back a page at a time, with `title` resolved to its name.\n\nThe site must belong to the client named in the route; otherwise 404. Unlike ListSites, an unknown site is a 404 rather than an empty page, because the site is checked before the query runs.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a site contact", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": 512,\n \"department\": \"Warehouse operations\",\n \"position\": \"Shift Manager\",\n \"title\": \"Ms\",\n \"forename\": \"Priya\",\n \"surname\": \"Raman\",\n \"telephone1\": \"0161 872 4415\",\n \"telephone2\": \"0161 872 4416\",\n \"mobile\": \"07700 900318\",\n \"email\": \"p.raman@example-northgate.co.uk\",\n \"fax\": \"0161 872 4417\",\n \"notes\": \"Best reached on the early shift, 06:00-14:00.\",\n \"canUseClientApp\": true,\n \"sector\": \"\"\n}" }, "description": "Adds a contact person to one of your own agency's sites. Site contacts are who the agency deals with day to day — they raise the work, and activities and cost-centre links hang off them.\n\nOnly `forename` is required. `siteId` in the body must match the `siteId` in the route, otherwise the request returns 400.\n\n`title` is a title **name**, not an id — one of the values published by the titles vocabulary. An unrecognised name returns 400 listing the accepted values.\n\nContacts are not name-checked for uniqueness: a site can hold two contacts with the same name. The site must belong to the client named in the route, otherwise 404. On success the response carries the new `contactPersonId` and a `Location` header pointing at GetSiteContactPersonById.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get site contact details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one contact person belonging to one of your own agency's sites, with their department, position and contact details.\n\nOnly **active** contacts are returned. A contact that has been deleted returns 404 here — unlike a site, which stays readable after archiving. Restore it with RestoreSiteContactPerson to read it again.\n\n`title` is resolved to its name. The site must belong to the client named in the route and the contact to that site; anything else returns 404, so existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a site contact", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"department\": \"Warehouse operations\",\n \"position\": \"Shift Manager\",\n \"title\": \"Ms\",\n \"forename\": \"Priya\",\n \"surname\": \"Raman\",\n \"telephone1\": \"0161 872 4415\",\n \"telephone2\": \"0161 872 4416\",\n \"mobile\": \"07700 900318\",\n \"email\": \"p.raman@example-northgate.co.uk\",\n \"fax\": \"0161 872 4417\",\n \"notes\": \"Best reached on the early shift, 06:00-14:00.\",\n \"canUseClientApp\": true,\n \"sector\": \"\"\n}" }, "description": "Updates one active contact person on one of your own agency's sites.\n\nThis 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. Send the complete record, not just the fields you are changing.\n\nA contact cannot be moved to another site — the site is not part of the request.\n\n`title` is a title name from the titles vocabulary; an unrecognised name returns 400. A deleted contact returns 404. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a site contact", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Deletes one contact person from one of your own agency's sites. This is a **soft delete**: the row is retained with its activities and cost-centre links, and RestoreSiteContactPerson can bring it back.\n\nA deleted contact disappears from ListSiteContactPersons **and** from GetSiteContactPersonById, which returns 404 for it. Restore is the only way to read it again, so record the `contactPersonId` before deleting.\n\nContact names are not reserved — another contact can immediately take the same name.\n\nThe site must belong to the client named in the route, and the contact to that site; otherwise 404. Deleting an already-deleted contact also returns 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Restore a deleted site contact", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/contact-persons/:id/restore", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "contact-persons", ":id", "restore" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Restores a contact person that was deleted with DeleteSiteContactPerson, returning them to the site's active contacts with their details and links intact.\n\nOnly a **deleted** contact can be restored. An active contact id, a contact belonging to another site, and a contact from another agency all return 404. There is no name clash to resolve, so a restore that finds its record always succeeds.\n\nThe request body is empty; the client, site and contact all come from the route.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "SiteCostCentres", "item": [ { "name": "List a site's cost centres", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/cost-centres", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "cost-centres" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." } ] }, "description": "Returns every cost centre linked to one of your own agency's sites.\n\nThis list is **not paged** and takes no filters — a site's cost centre links come back in full. Each entry carries the link's own id, which is what RemoveSiteCostCentre takes, not the cost centre id.\n\nThe list carries ids only. Read the cost centres themselves through the branch's cost centre endpoints for their names and details.\n\nThe site must belong to the client named in the route, otherwise 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Link a cost centre to a site", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/cost-centres", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "cost-centres" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"costCentreId\": 19\n}" }, "description": "Links one of your agency's cost centres to a site, so work at that site can be booked against it. The link is the whole record — there is nothing to update, only add and remove.\n\n**The cost centre must belong to the same branch as the site.** Cost centres are branch-scoped, and a cross-branch link returns 400. A site with no branch assigned cannot be linked to any cost centre, which also returns 400.\n\nA cost centre already linked to the site returns 400 rather than creating a duplicate, and a cost centre that does not exist returns 400.\n\nThe site must belong to the client named in the route, otherwise 404. On success the `Location` header points at ListSiteCostCentres, since a single link has no endpoint of its own.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Unlink a cost centre from a site", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/cost-centres/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "cost-centres", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes the link between a cost centre and one of your own agency's sites. The cost centre itself is untouched; only the link is deleted.\n\nThe `id` in the route is the **link's** id — the `siteCostCentreId` from ListSiteCostCentres — not the cost centre id.\n\nThis is a hard delete and there is no restore; re-link with AddSiteCostCentre if it was removed in error.\n\nThe site must belong to the client named in the route and the link to that site; otherwise 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "SiteInformation", "item": [ { "name": "Get a site's information sheet", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:id/information", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":id", "information" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns the information sheet for one of your own agency's sites — the practical briefing a consultant needs before placing anyone there: what the site does, what it requires of workers, and what facilities exist.\n\nA site has **at most one** information sheet, so this is addressed by site rather than by an id of its own.\n\nA site with no information sheet yet returns **404**, not an empty body. Create one with UpsertSiteInformation. A site that does not belong to the client named in the route also returns 404, so the two cases are indistinguishable from the status alone.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create or replace a site's information sheet", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:id/information", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":id", "information" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"information\": \"Chilled distribution centre serving 42 stores across the north west.\",\n \"staffRequirements\": \"Pickers and pallet truck drivers; own safety boots essential.\",\n \"actionToTake\": \"Call the shift supervisor before 05:30 for same-day cover.\",\n \"tempsUsed\": 60,\n \"peakPeriods\": \"October to early January, and Easter week.\",\n \"companySize\": \"250-500 employees\",\n \"noOfEmployees\": \"310\",\n \"minimumAge\": 18,\n \"safetyBoots\": true,\n \"hiViz\": true,\n \"smokingArea\": true,\n \"canteen\": true,\n \"agenciesUsed\": \"Two other suppliers on a shared rota.\",\n \"otherSites\": \"Shares a transport yard with the Salford depot.\",\n \"tempsDepartment\": \"Chilled picking\",\n \"assessmentRequired\": true,\n \"workersCanLogHoursViaApp\": true,\n \"importantSiteNotes\": \"No lone working after 22:00; gatehouse closes 23:00.\",\n \"workerAppRadius\": 0.5\n}" }, "description": "Creates the information sheet for one of your own agency's sites, or replaces it if one already exists. A site has at most one sheet, so there is no separate create and update.\n\nThis is a **full replacement**, not a partial merge: every field is written from the request, so a field you omit is set to null. Read the current sheet with GetSiteInformation and send it back with your changes applied, rather than sending only the fields you are changing.\n\n**Both outcomes return 200**, never 201 — a create and a replace are not distinguished by status. The response's `isNewlyCreated` tells you which happened.\n\nThe site must belong to the client named in the route, otherwise 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "SiteRateContracts", "item": [ { "name": "List a site's rate contracts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/rate-contracts", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "rate-contracts" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." } ] }, "description": "Returns a paged list of the rate contracts on one of your own agency's sites, each with its full rate pairs — this is the call that tells you what work at a site costs.\n\nA 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.\n\nDeleted contracts are excluded. There are no filters or sort options; the site's contracts come back a page at a time.\n\nThe site must belong to the client named in the route; otherwise 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a site rate contract", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/rate-contracts", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "rate-contracts" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"siteId\": 512,\n \"jobCategoryId\": 17,\n \"shiftId\": 5,\n \"jobDescription\": \"Order picking and pallet wrapping in a chilled environment.\",\n \"otRulesAndDetails\": \"Time and a half after 40 hours in a week.\",\n \"startTime\": \"2026-08-20T09:00:00\",\n \"endTime\": \"2026-08-20T09:00:00\",\n \"contactPersonId\": 88,\n \"healthAndSafety\": \"Chilled store, 2-4C. Manual handling briefing required.\",\n \"ppe\": \"Safety boots, hi-vis vest, thermal jacket.\",\n \"assessmentRequired\": true,\n \"assessmentDetails\": \"Manual handling assessment at the gatehouse.\",\n \"trainingRequired\": true,\n \"trainingDetails\": \"Half-day pallet truck training, renewed annually.\",\n \"inductionRequired\": true,\n \"inductionDetails\": \"Site induction on first shift, 45 minutes.\",\n \"holidayEntitlement\": 28,\n \"agriculture\": false,\n \"expensesPaid\": \"Mileage at 45p per mile beyond 25 miles.\",\n \"collectiveFacilities\": \"\",\n \"permanentVacancyAccess\": \"\",\n \"intervalOfPayments\": \"Weekly\",\n \"lengthOfTermination\": \"1 week\",\n \"frenchExtension\": false,\n \"isDailyRate\": false,\n \"dayRateRuleId\": 2,\n \"breakTime\": \"30 minutes unpaid\",\n \"restTimeBetweenShifts\": 11,\n \"natureOfBusiness\": \"\",\n \"isRolledUpHoliday\": false,\n \"rolledUpHolidayOn\": \"2026-04-06T00:00:00\",\n \"holidayPolicy\": \"Accrued at 12.07% of hours worked.\",\n \"periodOfExtendedHire\": \"\",\n \"rates\": [\n {\n \"rateTypeId\": 0,\n \"prePayRate\": 12.6,\n \"preChargeRate\": 16.8,\n \"preRequiredForHolidayPot\": true,\n \"prePayRateLimited\": 0,\n \"prePayRatePsc\": 0,\n \"preMarginRate\": 0,\n \"preMarginRateLimited\": 0,\n \"preMarginRatePsc\": 0,\n \"preUseInAod\": false,\n \"postPayRate\": 13.4,\n \"postChargeRate\": 17.65,\n \"postRequiredForHolidayPot\": true,\n \"postPayRateLimited\": 0,\n \"postPayRatePsc\": 0,\n \"postMarginRate\": 0,\n \"postMarginRateLimited\": 0,\n \"postMarginRatePsc\": 0,\n \"postUseInAod\": false\n }\n ]\n}" }, "description": "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.\n\nA 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.\n\n`jobCategoryId` and at least one entry in `rates` are required, and `siteId` in the body must match the `siteId` in the route.\n\n`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.\n\n**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.\n\n`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.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get site rate contract details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/rate-contracts/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "rate-contracts", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one rate contract belonging to one of your own agency's sites, with all of its rate pairs and assignment terms.\n\nA 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.\n\nDeleted contracts are **still returned here**, carrying `isDeleted` true, even though they are absent from ListSiteRateContracts. Check the flag before pricing anything against a contract you looked up by id.\n\nThe site must belong to the client named in the route and the contract to that site; anything else returns 404, so existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a site rate contract", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/rate-contracts/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "rate-contracts", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"jobDescription\": \"Order picking and pallet wrapping in a chilled environment.\",\n \"otRulesAndDetails\": \"Time and a half after 40 hours in a week.\",\n \"startTime\": \"2026-08-20T09:00:00\",\n \"endTime\": \"2026-08-20T09:00:00\",\n \"contactPersonId\": 88,\n \"healthAndSafety\": \"Chilled store, 2-4C. Manual handling briefing required.\",\n \"ppe\": \"Safety boots, hi-vis vest, thermal jacket.\",\n \"assessmentRequired\": true,\n \"assessmentDetails\": \"Manual handling assessment at the gatehouse.\",\n \"trainingRequired\": true,\n \"trainingDetails\": \"Half-day pallet truck training, renewed annually.\",\n \"inductionRequired\": true,\n \"inductionDetails\": \"Site induction on first shift, 45 minutes.\",\n \"holidayEntitlement\": 28,\n \"agriculture\": false,\n \"expensesPaid\": \"Mileage at 45p per mile beyond 25 miles.\",\n \"collectiveFacilities\": \"\",\n \"permanentVacancyAccess\": \"\",\n \"intervalOfPayments\": \"Weekly\",\n \"lengthOfTermination\": \"1 week\",\n \"frenchExtension\": false,\n \"dayRateRuleId\": 2,\n \"breakTime\": \"30 minutes unpaid\",\n \"restTimeBetweenShifts\": 11,\n \"natureOfBusiness\": \"\",\n \"isRolledUpHoliday\": false,\n \"rolledUpHolidayOn\": \"2026-04-06T00:00:00\",\n \"holidayPolicy\": \"Accrued at 12.07% of hours worked.\",\n \"periodOfExtendedHire\": \"\",\n \"ratesToAddOrUpdate\": [\n {\n \"rateTypeId\": 0,\n \"prePayRate\": 12.6,\n \"preChargeRate\": 16.8,\n \"preRequiredForHolidayPot\": true,\n \"prePayRateLimited\": 0,\n \"prePayRatePsc\": 0,\n \"preMarginRate\": 0,\n \"preMarginRateLimited\": 0,\n \"preMarginRatePsc\": 0,\n \"preUseInAod\": false,\n \"postPayRate\": 13.4,\n \"postChargeRate\": 17.65,\n \"postRequiredForHolidayPot\": true,\n \"postPayRateLimited\": 0,\n \"postPayRatePsc\": 0,\n \"postMarginRate\": 0,\n \"postMarginRateLimited\": 0,\n \"postMarginRatePsc\": 0,\n \"postUseInAod\": false\n }\n ],\n \"rateTypeIdsToRemove\": [\n 0\n ]\n}" }, "description": "Updates one rate contract on one of your own agency's sites.\n\nThe contract's own fields are a **full replacement** — every mutable field is written from the request, so an omitted field is set to null.\n\n**The rates are not.** Rates change by delta rather than by replacement: `ratesToAddOrUpdate` adds a rate pair for a rate type the contract does not have, or overwrites the pair it does, and `rateTypeIdsToRemove` drops pairs by rate type. Omitting both leaves every existing rate untouched. A rate type may appear only once in `ratesToAddOrUpdate`, and a `rateTypeIdsToRemove` entry the contract does not hold returns 400.\n\n**A contract must keep at least one rate pair.** A request that would remove them all returns 400.\n\n`jobCategoryId`, `shiftId` and `isDailyRate` are fixed at creation and are not part of this request. Where `isDailyRate` is true, `dayRateRuleId` must still be supplied and greater than 0.\n\nAs on create, a margin shortfall is a **warning, not an error**: the update succeeds and `warnings` names the pairs that fell below their rate type's minimum.\n\nThe site must belong to the client named in the route and the contract to that site; otherwise 404.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a site rate contract", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:siteId/rate-contracts/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":siteId", "rate-contracts", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "siteId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Deletes one rate contract from one of your own agency's sites. This is a **soft delete**: the row and its rate pairs are retained, so historical work priced against this contract keeps its rates.\n\nThere is **no restore endpoint** for a rate contract, unlike a site or a site contact. A deleted contract drops out of ListSiteRateContracts but is still readable through GetSiteRateContractById with `isDeleted` true, and UpdateSiteRateContract still accepts it — but nothing sets `isDeleted` back to false, so treat the delete as final and create a replacement contract instead.\n\nThe site must belong to the client named in the route and the contract to that site; otherwise 404. Deleting an already-deleted contract succeeds again and re-stamps the audit fields.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "Sites", "item": [ { "name": "List a client's sites", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." } ] }, "description": "Returns a paged list of the **active** sites belonging to one of your own agency's clients. Archived sites are excluded; read one by id with GetSiteById if you need to inspect it.\n\nA `clientId` that does not exist, belongs to another agency, or sits under a branch the Recruso user behind your API app cannot access returns an empty page rather than 404 — the client is not looked up, only used to scope the query, and no site of a client outside those branches is ever returned.\n\n`siteName` matches case-insensitively on any part of the name. Results are paged 20 per page by default. Sort with `sortColumn` (`sitename`, `town`, `postcode`, `createdon` or `modifiedon`) and `sortOrder` (`asc` or `desc`); an unrecognised `sortColumn` falls back to `sitename` rather than failing.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a site", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"clientId\": 137,\n \"siteName\": \"Trafford Park DC\",\n \"memo\": \"Gatehouse sign-in required; ask for the shift supervisor.\",\n \"gre\": 0,\n \"grn\": 0,\n \"address1\": \"Northgate House\",\n \"address2\": \"22 Ashburton Road West\",\n \"town\": \"Trafford Park\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postCode\": \"M17 1RU\",\n \"telephone1\": \"0161 872 4410\",\n \"telephone2\": \"0161 872 4411\",\n \"fax\": \"0161 872 4412\",\n \"email\": \"trafford@example-northgate.co.uk\",\n \"invoiceMethodId\": 1,\n \"useSiteAddressForInvoice\": true,\n \"useSiteEmailForInvoice\": false,\n \"branchId\": 4,\n \"timesheetEmail\": \"timesheets@example-northgate.co.uk\"\n}" }, "description": "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.\n\nOnly `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.\n\n`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`.\n\n`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.\n\nA 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.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get site details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns the full record for one site, including its address, invoicing preferences and archive history.\n\nUnlike ListSites, this **does** return archived sites. Check `isDeleted` before treating the site as usable — an archived site still resolves here so that an integration holding a stale id can tell the difference between a site that was archived and one that never existed.\n\nThe site must belong to the client named in the route. A site id from a different client, from another agency, or under a client whose branch the Recruso user behind your API app cannot access returns 404 rather than 403, so existence is never disclosed. A site inherits its client's branch, and that — not the site's own `branchId` — is what decides access to the site and everything beneath it.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a site", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"siteName\": \"Trafford Park DC\",\n \"memo\": \"Gatehouse sign-in required; ask for the shift supervisor.\",\n \"gre\": 0,\n \"grn\": 0,\n \"invoiceMethodId\": 1,\n \"useSiteAddressForInvoice\": true,\n \"useSiteEmailForInvoice\": false,\n \"address1\": \"Northgate House\",\n \"address2\": \"22 Ashburton Road West\",\n \"town\": \"Trafford Park\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postCode\": \"M17 1RU\",\n \"telephone1\": \"0161 872 4410\",\n \"telephone2\": \"0161 872 4411\",\n \"fax\": \"0161 872 4412\",\n \"email\": \"trafford@example-northgate.co.uk\",\n \"timesheetEmail\": \"timesheets@example-northgate.co.uk\"\n}" }, "description": "Updates one site belonging to one of your own agency's clients.\n\nThis 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. Send the complete record, not just the fields you are changing.\n\nA site's **branch and client cannot be changed here** — neither is part of the request. A site stays with the client it was created under.\n\nThe renamed site must not collide with another of the client's active sites (400) or with an archived one (**409**, carrying the archived `siteId`, exactly as in CreateSite).\n\nThe site must belong to the client named in the route; otherwise 404. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Archive a site", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":id" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Archives one site belonging to one of your own agency's clients. This is a **soft delete**: the row is retained with its history, `siteArchivedBy` and `siteArchivedOn` are stamped, and RestoreSite can bring it back.\n\nAn archived site drops out of ListSites and out of the sites embedded in ListClientsWithSites, but GetSiteById still returns it with `isDeleted` true.\n\n**The name stays reserved.** Creating or renaming another site to the archived site's name returns 409 until the archived site is restored or renamed.\n\nThe site must belong to the client named in the route; otherwise 404. Archiving a site that is already archived is not rejected — it re-stamps the archive audit fields.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Restore an archived site", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/clients/:clientId/sites/:id/restore", "host": [ "{{baseUrl}}" ], "path": [ "v1", "clients", ":clientId", "sites", ":id", "restore" ], "variable": [ { "key": "clientId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"clientId\": 137,\n \"id\": 512\n}" }, "description": "Restores a site that was archived with DeleteSite, returning it to the client's active sites with its address and history intact.\n\nOnly an **archived** site can be restored. An active site id, a site belonging to another client, and a site from another agency all return 404.\n\nIf the client has since gained an active site with the same name, the restore returns 400 — rename the active site first, because two active sites of one client cannot share a name.\n\nThe request body is empty; the client and site come from the route. On success the restored site is returned.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] } ] }, { "name": "Workers", "description": "Workers and their onboarding: the worker record itself, and the compliance documents, driving licences, Driver CPC records, employment history and files that hang off it. One tag per sub-resource, so each reads as its own small CRUD surface.", "item": [ { "name": "WorkerActivities", "item": [ { "name": "List a worker's activities", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/activities", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "activities" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns a worker's activity feed in your own agency, newest activity first.\n\nEach entry says when the activity happened, what was said, what was done and when to call back, together with the Recruso user who logged it. The list is not paged, so a worker contacted often returns a long one.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Log an activity against a worker", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/activities", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "activities" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"eventId\": \"AAMkAGI2TG93AAA=\",\n \"activityDate\": \"2026-09-04T14:32:00\",\n \"activityTypeId\": 4,\n \"description\": \"Called about Thursday nights at Trafford Park; worker is interested.\",\n \"actionTaken\": \"Pencilled in for the Thursday shift; to confirm Monday.\",\n \"nextCallDate\": \"2026-09-08T09:00:00\"\n}" }, "description": "Adds an entry to a worker's activity feed in your own agency: when you spoke to them, what was said, and what was done about it.\n\nThe feed only ever accumulates — an entry is a record of something that happened, so nothing here replaces or deduplicates what is already there.\n\n`ActivityDate` is required and is UK local time, not UTC. `ActivityTypeId` must be an activity type in your agency's lookup; one that does not exist returns 400. `NextCallDate` is when to call back, and is what a call-back list is built from.\n\nThe activity records the consultant it involved as well as who logged it. Both are your own credentials, and the consultant is fixed here — correcting the entry later does not move it. `EventId` is the Outlook calendar event id when the activity was raised as a calendar entry, and is likewise set only here.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's activities", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "activities", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single entry from a worker's activity feed in your own agency.\n\nAn entry that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Correct one of a worker's activities", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "activities", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"id\": 9930,\n \"activityDate\": \"2026-09-04T14:32:00\",\n \"activityTypeId\": 4,\n \"description\": \"Called about Thursday nights at Trafford Park; worker is interested.\",\n \"actionTaken\": \"Pencilled in for the Thursday shift; to confirm Monday.\",\n \"nextCallDate\": \"2026-09-08T09:00:00\"\n}" }, "description": "Corrects an entry already in a worker's activity feed in your own agency.\n\nThis is a **full replacement** of that one entry, not a partial merge: a field you omit is set to null. Use it to fix an entry that was logged wrongly — a later call is a new entry, not an edit of the one before it.\n\nThe Recruso user recorded against the entry stays the one who logged it; only `modifiedBy` and `modifiedOn` move, and both are set from your credentials and the current UK local time.\n\nAn entry that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's activities", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/activities/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "activities", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes an entry from a worker's activity feed in your own agency.\n\n**This is permanent.** The record carries no soft-delete column, so the entry is gone from the feed. A feed is a record of what happened, so this is for an entry logged against the wrong worker or entered twice — not for tidying old activity.\n\nAn entry that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerAvailability", "item": [ { "name": "List a worker's availability", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/availability", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "availability" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns the days a worker in your own agency is, or is not, available between `from` and `to`, both inclusive. Each entry has a date, one of your agency's availability statuses and, optionally, a start and a finish time. A day with no entry is a day the worker is available.\n\nBoth `from` and `to` are required, and the range may cover no more days than your agency shows at once in Recruso CRM, counting both ends: at most 30. A range that is missing, reversed or wider returns 400. The list is not paged.\n\nEntries are ordered by date, then by start time, those with none first. A worker may hold two entries on one date when your agency allows it.\n\nA worker in another agency, under a branch the Recruso user behind your API app cannot reach, or deleted under data-protection law returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Record a day of a worker's availability", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/availability", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "availability" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"date\": \"2026-11-03\",\n \"startTime\": \"07:00:00\",\n \"finishTime\": \"19:00:00\",\n \"availabilityStatusId\": 3\n}" }, "description": "Records a day a worker in your own agency is, or is not, available: a date, one of your agency's availability statuses and, optionally, a start and a finish time. Either time may be sent alone, and a finish earlier than the start passes midnight.\n\nThe date must be no more than 20 days before today and no more than a year after it, in the UK. A worker holds one entry a date, or two when your agency allows more than one status a day; a date already full returns 400. A status that affects a worker's AWR parity cannot be recorded through this API, and one that is not your agency's returns 400.\n\n`doNotAccrue` is set from your agency's holiday accrual setting for the worker's type, for limited-company and PSC workers only, and kept as it was even if the setting changes later. If your agency's settings hold two entries for that type, the request returns 400 until they are corrected in Recruso CRM.\n\nA worker in another agency, under a branch the Recruso user behind your API app cannot reach, or deleted under data-protection law returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's availability entries", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/availability/:availabilityId", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "availability", ":availabilityId" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "availabilityId", "value": "", "description": "Required." } ] }, "description": "Returns a single availability entry of a worker in your own agency.\n\nAn entry that belongs to a different worker returns 404, as does a worker in another agency, under a branch the Recruso user behind your API app cannot reach, or deleted under data-protection law — never 403, so existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Correct one of a worker's availability entries", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/availability/:availabilityId", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "availability", ":availabilityId" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "availabilityId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"date\": \"2026-11-03\",\n \"startTime\": \"07:00:00\",\n \"finishTime\": \"19:00:00\",\n \"availabilityStatusId\": 3\n}" }, "description": "Corrects an availability entry of a worker in your own agency.\n\nThis is a **full replacement** of the entry's date, times and status, not a partial merge: a time you omit is cleared, and times are kept to the nearest minute. `doNotAccrue` and `createdOn` are kept as they were; `modifiedOn` is set to the current UK local time.\n\nBoth the entry as stored and the entry as sent must fall within the window — no more than 20 days before today and no more than a year after it — and neither may hold a status that affects a worker's AWR parity: an entry that already does cannot be changed through this API, nor can one whose stored status is not one of your agency's. Moving an entry to a date that is already full returns 400; correcting it on its own date does not count against the limit. Each of these returns 400.\n\nAn entry that belongs to a different worker returns 404, as does a worker in another agency, under a branch the Recruso user behind your API app cannot reach, or deleted under data-protection law — never 403, so existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's availability entries", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/availability/:availabilityId", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "availability", ":availabilityId" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "availabilityId", "value": "", "description": "Required." } ] }, "description": "Removes an availability entry of a worker in your own agency, which makes the worker available again on that date: no \"available\" entry is written in its place.\n\nThe entry must be dated no more than 20 days before today and no more than a year after it, and must hold one of your agency's statuses and not one that affects a worker's AWR parity; otherwise the request returns 400 and the entry stays.\n\nAn entry that belongs to a different worker returns 404, as does a worker in another agency, under a branch the Recruso user behind your API app cannot reach, or deleted under data-protection law — never 403, so existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerCompliances", "item": [ { "name": "List a worker's compliance documents", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/compliances", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "compliances" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns every document held for a worker in your own agency, oldest first — the worker's right-to-work register, including documents that have since expired.\n\nThe same document type can appear several times: each renewal is its own record with its own dates. The list is not paged. A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Add a compliance document to a worker", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/compliances", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "compliances" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"complianceId\": 3,\n \"startDate\": \"2026-01-15\",\n \"endDate\": \"2031-01-14\"\n}" }, "description": "Adds one document to a worker's right-to-work register in your own agency.\n\nDocuments accumulate rather than replace one another. A worker legitimately holds the same document type several times across the years — a renewal is a new document with its own dates, not an edit of the one it renews — so nothing here rejects a type the worker already has.\n\n`EndDate` must not be before `StartDate`, and `ComplianceId` must be a compliance type in your agency's lookup; one that does not exist returns 400. A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's compliance documents", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/compliances/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "compliances", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single document from a worker's right-to-work register in your own agency.\n\nA document that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Correct one of a worker's compliance documents", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/compliances/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "compliances", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"id\": 7311,\n \"complianceId\": 3,\n \"startDate\": \"2026-01-15\",\n \"endDate\": \"2031-01-14\"\n}" }, "description": "Corrects a document already held for a worker in your own agency — its type, or the dates it runs between.\n\nThis is a **full replacement** of that one document, not a partial merge: a field you omit is set to null.\n\nUse it to fix a document that was recorded wrongly, not to record a renewal. A renewal is a new document with its own dates: overwriting the old one would erase the period it covered from the right-to-work register.\n\nA document that belongs to a different worker, or to another agency, returns 404 rather than 403. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time; they are not taken from the request.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's compliance documents", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/compliances/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "compliances", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes one document from a worker's right-to-work register in your own agency.\n\n**This is permanent.** The record carries no soft-delete column, so there is no restore and no retained copy — the document and the period it evidenced are gone from the register. Removing a document is for one recorded in error; an expired document is part of the compliance history and belongs where it is.\n\nA worker must always hold at least one compliance document, so removing the last one returns 400. To replace a worker's only document, add the right one first and remove the wrong one afterwards.\n\nA document that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerCpcLicenceCategories", "item": [ { "name": "List a worker's Driver CPC entitlements", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-licence-categories", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-licence-categories" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns every Driver CPC entitlement recorded for a worker in your own agency, earliest start date first.\n\nExpired entitlements are listed alongside current ones: the record keeps them, and `validUntil` on each says which is which. A class can appear more than once — each renewal is its own period. The list is not paged.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Add a Driver CPC entitlement to a worker", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-licence-categories", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-licence-categories" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"vehicleCategoryId\": 2,\n \"validFrom\": \"2021-09-10\",\n \"validUntil\": \"2026-09-09\"\n}" }, "description": "Records a vehicle class a worker in your own agency holds Driver CPC entitlement for, and the period it runs.\n\nThis is not the same as the worker's vehicle categories, which say what they can drive: this says what their CPC covers and until when. Both dates are required — the columns are NOT NULL — and `ValidUntil` must not be before `ValidFrom`.\n\nEntitlements accumulate rather than replace one another: a renewed CPC is a new record for the same class with a later period, which is what keeps the history of what the worker was entitled to when.\n\n`VehicleCategoryId` must be an id from the platform Vehicle categories vocabulary; one that does not exist returns 400. A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's Driver CPC entitlements", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-licence-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-licence-categories", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single Driver CPC entitlement recorded for a worker in your own agency.\n\nA record that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update one of a worker's Driver CPC entitlements", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-licence-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-licence-categories", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"id\": 3310,\n \"vehicleCategoryId\": 2,\n \"validFrom\": \"2021-09-10\",\n \"validUntil\": \"2026-09-09\"\n}" }, "description": "Replaces a Driver CPC entitlement recorded for a worker in your own agency — its vehicle class, or the period it runs.\n\nUse it to fix a record entered wrongly. A renewed entitlement is a new record with its own period: overwriting the old one would erase what the worker was entitled to before.\n\nAll three fields are required. A record that belongs to a different worker, or to another agency, returns 404 rather than 403. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's Driver CPC entitlements", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-licence-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-licence-categories", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes a Driver CPC entitlement from a worker in your own agency.\n\n**This is permanent.** The record carries no soft-delete column. An expired entitlement is part of the worker's CPC history and belongs where it is; use this for one recorded in error.\n\nA record that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerCpcTraining", "item": [ { "name": "List a worker's Driver CPC training periods", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns every Driver CPC training period recorded for a worker in your own agency, earliest start date first, each with the number of modules recorded in it and the hours they add up to.\n\nUse the hours to see how far through the periodic training a worker is; the modules themselves are listed by their own operation. The list is not paged.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Add a Driver CPC training period to a worker", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"trainingFrom\": \"2021-09-10\",\n \"trainingUntil\": \"2026-09-09\",\n \"completedByRequiredDate\": false\n}" }, "description": "Opens a Driver CPC training period for a worker in your own agency — the window the periodic training has to be completed in.\n\nThe period holds no training on its own: the modules completed within it are recorded against it one at a time, and the period reports how many there are and the hours they add up to.\n\nBoth dates are required, and `TrainingUntil` must not be before `TrainingFrom`. A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's Driver CPC training periods", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single Driver CPC training period for a worker in your own agency, with the number of modules recorded in it and the hours they add up to. The modules themselves are listed by their own operation.\n\nA period that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update one of a worker's Driver CPC training periods", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"id\": 4410,\n \"trainingFrom\": \"2021-09-10\",\n \"trainingUntil\": \"2026-09-09\",\n \"completedByRequiredDate\": false\n}" }, "description": "Replaces a Driver CPC training period for a worker in your own agency — the dates it runs between, and whether the required hours were completed in time.\n\nThe modules recorded in the period are left exactly as they are. Marking the period complete does not check the hours: that is a judgement the agency makes, and the hours are reported alongside it so a reader can see both.\n\nA period that belongs to a different worker, or to another agency, returns 404 rather than 403. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's Driver CPC training periods", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes a Driver CPC training period from a worker in your own agency.\n\n**This is permanent, and it takes the modules with it.** A module is recorded against the period rather than against the worker, so it has nowhere to live once the period is gone. Neither table carries a soft-delete column.\n\nA period that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerCpcTrainingModules", "item": [ { "name": "List the modules in a Driver CPC training period", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training/:trainingId/modules", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training", ":trainingId", "modules" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "trainingId", "value": "", "description": "Required." } ] }, "description": "Returns every module recorded within one of a worker's Driver CPC training periods in your own agency, earliest training date first, with the hours they add up to.\n\nThe list is not paged. A worker or period belonging to another agency returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Record a module against a Driver CPC training period", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training/:trainingId/modules", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training", ":trainingId", "modules" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "trainingId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"trainingId\": 4410,\n \"trainingDate\": \"2024-02-19\",\n \"trainingCentre\": \"Northgate Driver Training, Salford\",\n \"module\": \"Drivers' hours and tachograph rules\",\n \"hoursCompleted\": 7\n}" }, "description": "Records a module a worker in your own agency has completed within one of their Driver CPC training periods — when it was taken, where, what it covered and how many hours it counted for.\n\nA module belongs to the **period**, not to the worker: it is nested under the period, and removing that period removes its modules too. The hours are summed onto the period, so they are how far through the periodic training the worker is.\n\n`TrainingDate` is required. Nothing here checks the date falls inside the period, or that the hours stay under the total the training requires: both are matters of record rather than rules this API invents.\n\nA worker or period belonging to another agency returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Correct a module in a Driver CPC training period", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training/:trainingId/modules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training", ":trainingId", "modules", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "trainingId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"trainingId\": 4410,\n \"id\": 8815,\n \"trainingDate\": \"2024-02-19\",\n \"trainingCentre\": \"Northgate Driver Training, Salford\",\n \"module\": \"Drivers' hours and tachograph rules\",\n \"hoursCompleted\": 7\n}" }, "description": "Corrects a module already recorded within one of a worker's Driver CPC training periods in your own agency.\n\nThis is a **full replacement** of that one module, not a partial merge: a field you omit is set to null. A module cannot be moved to a different period — record it against the right one and remove the wrong one.\n\nA module that belongs to a different period, a different worker, or another agency returns 404 rather than 403. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove a module from a Driver CPC training period", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/cpc-training/:trainingId/modules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "cpc-training", ":trainingId", "modules", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "trainingId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes a module recorded within one of a worker's Driver CPC training periods in your own agency, and with it the hours it contributed.\n\n**This is permanent.** The record carries no soft-delete column. Use it for a module recorded in error or against the wrong period.\n\nA module that belongs to a different period, a different worker, or another agency returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerDocuments", "item": [ { "name": "List a worker's documents", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/documents", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "documents" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns the files held against a worker in your own agency, most recently uploaded first.\n\nEach entry says what the file was called, when it was uploaded and who uploaded it. The files themselves cannot be downloaded through the API. The list is not paged.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Upload a document against a worker", "request": { "method": "POST", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/documents", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "documents" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Adds a file to a worker's documents in your own agency, sent as `multipart/form-data` with the file in a part named `file`.\n\nAccepted types are doc, docx, xls, xlsx, pdf, jpg, jpeg, png, gif, tif, tiff, msg, up to 50 MB. Anything else returns 400.\n\n**An upload cannot be corrected.** The record carries no modified-by audit, so there is nothing to record a correction with: replace a document by uploading the new one and removing the old.\n\nThe name you upload is kept as the document name, and the file is stored under a generated identifier instead, so a file whose name another agency has already used is fine. Documents are held in private storage, and the response does not say where.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's documents", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/documents/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "documents", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single document held against a worker in your own agency.\n\nThis is the record, not the file: what it was called, when it was uploaded and by whom. The file itself cannot be downloaded through the API.\n\nA document that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's documents", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/documents/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "documents", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes a document from a worker in your own agency, **and deletes the stored file with it**.\n\n**This is permanent.** The record carries no soft-delete column and the file is gone from storage, so neither the entry nor its contents can be recovered.\n\nA document that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Download one of a worker's documents", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/documents/:id/content", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "documents", ":id", "content" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns the file itself for a document held against a worker in your own agency.\n\nIt is always sent as an attachment, named as it was uploaded, with a media type decided by its extension rather than the one it was uploaded with. The file comes from the API and nowhere else: documents are held in private storage, and where is never disclosed.\n\nA document that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed. So does a document whose file is no longer in storage.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerImage", "item": [ { "name": "Download a worker's profile image", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/image", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "image" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns the profile photograph itself for a worker in your own agency.\n\nIt is always sent as an attachment, with a media type decided by its extension rather than the one it was uploaded with. The image comes from the API and nowhere else; where it is stored is never disclosed.\n\nA worker who has no profile image returns 404, as does a worker id belonging to another agency — which is deliberate, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Set a worker's profile image", "request": { "method": "PUT", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/image", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "image" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Sets the profile photograph for a worker in your own agency, sent as `multipart/form-data` with the image in a part named `file`.\n\nAccepted types are jpg, jpeg, png, gif, up to 3 MB. Anything else returns 400.\n\nA worker has **at most one** profile image, so this replaces whatever is there rather than adding to it, and the image it replaces is deleted from storage. The record keeps no history and no audit of who changed it, so the previous image cannot be recovered.\n\nReturns 204 with no body. Read the image back through `GET` on the same route.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove a worker's profile image", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/image", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "image" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Removes the profile photograph from a worker in your own agency, **and deletes the stored image with it**.\n\n**This is permanent.** The record keeps no history and the image is gone from storage, so neither can be recovered.\n\nA worker who has no profile image returns 404, as does a worker id belonging to another agency, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerLicenceConvictions", "item": [ { "name": "List the convictions against a worker's licence", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:licenceId/convictions", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":licenceId", "convictions" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "licenceId", "value": "", "description": "Required." } ] }, "description": "Returns every conviction recorded against one of a worker's licences in your own agency, oldest first, with the total penalty points they add up to.\n\nExpired convictions are listed alongside current ones — the record keeps them, and the expiry date on each says which is which. The total counts every conviction listed, expired ones included. The list is not paged.\n\nA worker or licence belonging to another agency returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Record a conviction against a worker's licence", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:licenceId/convictions", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":licenceId", "convictions" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "licenceId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"licenceId\": 5120,\n \"convictionCodeId\": 12,\n \"convictedDate\": \"2025-03-18\",\n \"convictionExpiryDate\": \"2029-03-17\",\n \"licencePoints\": 3,\n \"convictionNotes\": \"Speeding on the M60; fixed penalty accepted.\"\n}" }, "description": "Records a driving conviction against one of a worker's licences in your own agency.\n\nA conviction is against the **licence**, not against the person: it is nested under the licence, and removing that licence removes its convictions too.\n\n`ConvictionCodeId` must be an id from the platform Driving conviction codes vocabulary; one that does not exist returns 400. `ConvictionExpiryDate` must not be before `ConvictedDate`, and `LicencePoints` cannot be negative.\n\nA worker or licence belonging to another agency returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one conviction against a worker's licence", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:licenceId/convictions/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":licenceId", "convictions", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "licenceId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single conviction recorded against one of a worker's licences in your own agency.\n\nA conviction that belongs to a different licence, a different worker, or another agency returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Correct a conviction against a worker's licence", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:licenceId/convictions/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":licenceId", "convictions", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "licenceId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"licenceId\": 5120,\n \"id\": 7740,\n \"convictionCodeId\": 12,\n \"convictedDate\": \"2025-03-18\",\n \"convictionExpiryDate\": \"2029-03-17\",\n \"licencePoints\": 3,\n \"convictionNotes\": \"Speeding on the M60; fixed penalty accepted.\"\n}" }, "description": "Corrects a conviction already recorded against one of a worker's licences in your own agency.\n\nThis is a **full replacement** of that one conviction, not a partial merge: a field you omit is set to null. A conviction cannot be moved to a different licence — record it against the right one and remove the wrong one.\n\n`ConvictionCodeId` must be an id from the platform Driving conviction codes vocabulary; one that does not exist returns 400.\n\nA conviction that belongs to a different licence, a different worker, or another agency returns 404 rather than 403. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time; they are not taken from the request.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove a conviction from a worker's licence", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:licenceId/convictions/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":licenceId", "convictions", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "licenceId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes a conviction recorded against one of a worker's licences in your own agency.\n\n**This is permanent.** The record carries no soft-delete column, so there is nothing to restore. A conviction that has expired is part of the licence history and belongs where it is; use this for one recorded in error.\n\nA conviction that belongs to a different licence, a different worker, or another agency returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerLicences", "item": [ { "name": "List a worker's driving licences", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns every driving licence recorded for a worker in your own agency, oldest first, each with a count of the convictions against it.\n\nMost workers hold one licence or none; the record allows several because a replacement licence is recorded rather than overwriting the one it replaces. The list is not paged. A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Add a driving licence to a worker", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"licenceNumber\": \"BAKER905124A99AB\",\n \"issueDate\": \"2019-06-03\",\n \"expiryDate\": \"2029-06-02\",\n \"issueNumberChecked\": true\n}" }, "description": "Records a driving licence against a worker in your own agency.\n\n**The licence number is unique across your whole agency**, not just across this worker: a number already recorded returns 400, and the reply does not say which worker holds it. `ExpiryDate` must not be before `IssueDate`.\n\nConvictions are recorded against the licence rather than against the worker, and are managed through the licence's own convictions operations.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's driving licences", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single driving licence held by a worker in your own agency, with a count of the convictions recorded against it. The convictions themselves are listed by their own operation.\n\nA licence that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update one of a worker's driving licences", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"id\": 5120,\n \"licenceNumber\": \"BAKER905124A99AB\",\n \"issueDate\": \"2019-06-03\",\n \"expiryDate\": \"2029-06-02\",\n \"issueNumberChecked\": true\n}" }, "description": "Replaces a driving licence held by a worker in your own agency.\n\nThis is a **full replacement** of that one licence, not a partial merge: a field you omit is set to null. The convictions recorded against the licence are left exactly as they are.\n\n**The licence number is unique across your whole agency**, so a number another licence already carries returns 400, and the reply does not say which worker holds it. `ExpiryDate` must not be before `IssueDate`.\n\nA licence that belongs to a different worker, or to another agency, returns 404 rather than 403. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time; they are not taken from the request.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's driving licences", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/licences/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "licences", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes a driving licence from a worker in your own agency.\n\n**This is permanent, and it takes the convictions with it.** A conviction is recorded against the licence rather than against the person, so it has no meaning once the licence is gone. Neither table carries a soft-delete column, so nothing is retained and nothing can be restored — use this for a licence recorded in error, not for one that has expired.\n\nA licence that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerPreviousEmployments", "item": [ { "name": "List a worker's previous employments", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/previous-employments", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "previous-employments" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns every previous employment recorded for a worker in your own agency, oldest record first — which is the order they were entered in, not the order the jobs were held. Sort on `workFrom` if you need the working history in sequence.\n\nThe list is not paged. A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Add a previous employment to a worker", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/previous-employments", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "previous-employments" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"clientName\": \"Northgate Logistics Ltd\",\n \"companyRegNumber\": \"04512339\",\n \"telephone\": \"0161 496 0142\",\n \"fax\": \"0161 496 0143\",\n \"email\": \"hr@northgate-logistics.example.co.uk\",\n \"workerPosition\": \"Warehouse operative\",\n \"contactPersonName\": \"Priya Raval\",\n \"contactPersonPosition\": \"Shift manager\",\n \"reasonForLeft\": \"Site closed\",\n \"experience\": \"Picking and packing, plus counterbalance FLT from 2023.\",\n \"workFrom\": \"2022-04-04\",\n \"workTo\": \"2025-11-28\",\n \"honest\": true,\n \"reEmploy\": true,\n \"abilityRank\": 4,\n \"timeKeepingRank\": 5,\n \"referenceSentDate\": \"2026-01-06\",\n \"referenceOutcome\": \"Received 14 January 2026, satisfactory\"\n}" }, "description": "Records a job a worker in your own agency held before registering, together with the reference chased for it.\n\n`ClientName` and `CompanyRegNumber` are required — both are NOT NULL in the record. `WorkTo` must not be before `WorkFrom`. Everything about the reference — when it was sent, what came back, whether the employer would re-employ — is optional, because it arrives after the employment itself is recorded.\n\nEmployments accumulate: a worker has as many as they have had jobs, and nothing here rejects two records for the same employer.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get one of a worker's previous employments", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/previous-employments/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "previous-employments", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single previous employment recorded for a worker in your own agency, with the state of the reference chased for it.\n\nA record that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update one of a worker's previous employments", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/previous-employments/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "previous-employments", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"workerId\": 4821,\n \"id\": 6602,\n \"clientName\": \"Northgate Logistics Ltd\",\n \"companyRegNumber\": \"04512339\",\n \"telephone\": \"0161 496 0142\",\n \"fax\": \"0161 496 0143\",\n \"email\": \"hr@northgate-logistics.example.co.uk\",\n \"workerPosition\": \"Warehouse operative\",\n \"contactPersonName\": \"Priya Raval\",\n \"contactPersonPosition\": \"Shift manager\",\n \"reasonForLeft\": \"Site closed\",\n \"experience\": \"Picking and packing, plus counterbalance FLT from 2023.\",\n \"workFrom\": \"2022-04-04\",\n \"workTo\": \"2025-11-28\",\n \"honest\": true,\n \"reEmploy\": true,\n \"abilityRank\": 4,\n \"timeKeepingRank\": 5,\n \"referenceSentDate\": \"2026-01-06\",\n \"referenceOutcome\": \"Received 14 January 2026, satisfactory\"\n}" }, "description": "Replaces a previous employment recorded for a worker in your own agency.\n\nThis is a **full replacement** of that one record, not a partial merge: a field you omit is set to null. Recording a reference that has come back therefore means sending the employment's other fields with it, not just the outcome.\n\nA record that belongs to a different worker, or to another agency, returns 404 rather than 403. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time; they are not taken from the request.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Remove one of a worker's previous employments", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/previous-employments/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "previous-employments", ":id" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." }, { "key": "id", "value": "", "description": "Required." } ] }, "description": "Removes a previous employment from a worker in your own agency.\n\n**This is permanent.** The record carries no soft-delete column, so the employment and the reference recorded against it are both gone. Use it for a record entered in error.\n\nA record that belongs to a different worker, or to another agency, returns 404 rather than 403, so its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "Workers", "item": [ { "name": "List workers", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers" ], "variable": [] }, "description": "Returns a paged list of the workers in your own agency. Sent without filters it lists them all; with filters it is how you find a worker — by name, email address, worker number, branch or current status. Filters combine, so a worker must match every one you send.\n\nEach entry is a summary rather than the full record: who the worker is, how they are engaged — branch, cost centre, worker type, status, rating and transport — and how to reach them. Call GetWorkerById for one worker's complete details; tax, bank and compliance details never appear in this list.\n\n`name` matches case-insensitively on any part of the forename, surname or known-as name, or of the full name, so `john smi` finds John Smith. `email` is a case-insensitive match on the **whole** address: part of an address matches nothing. `workerNumber` and `branchId` are exact matches. `workerStatusTypeId` matches the worker's current status, as an id from the worker status types vocabulary; an id that does not exist returns 400.\n\nWorkers who have left and workers engaged through a subcontractor are included. A worker whose record has been GDPR-deleted never appears, and neither does a worker registered against a branch the Recruso user behind your API app cannot access — even when `branchId` names that branch.\n\nResults are paged: 25 per page by default, capped at 100. `pageNumber` below 1 is treated as 1. Sort with `sortColumn` (`surname`, `forename`, `workernumber`, `createdon` or `modifiedon`) and `sortOrder` (`asc` or `desc`); an unrecognised column sorts by surname.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a worker", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"branchId\": 4,\n \"compliances\": [\n {\n \"complianceId\": 3,\n \"startDate\": \"2026-01-15\",\n \"endDate\": \"2031-01-14\"\n }\n ],\n \"titleId\": 2,\n \"forename\": \"Alice\",\n \"surname\": \"Baker\",\n \"knownAs\": \"Ali\",\n \"initials\": \"AB\",\n \"birthDate\": \"1990-04-12\",\n \"genderId\": 2,\n \"maritalStatusId\": 1,\n \"ethnicOriginId\": 3,\n \"nationalityId\": 14,\n \"address1\": \"12 High Street\",\n \"address2\": \"Flat 2\",\n \"town\": \"Manchester\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postalCode\": \"M1 1AA\",\n \"telephone1\": \"0161 496 0123\",\n \"mobile\": \"07700 900123\",\n \"email\": \"alice.baker@example.co.uk\",\n \"nextOfKinFullName\": \"Jane Baker\",\n \"nextOfKinContactNumber\": \"07700 900456\",\n \"nextOfKinEmailAddress\": \"jane.baker@example.co.uk\",\n \"niNumber\": \"AB123456C\",\n \"formId\": 1,\n \"niCategoryId\": 1,\n \"statementA\": true,\n \"statementB\": false,\n \"statementC\": false,\n \"noStatement\": false,\n \"employeeTaxCode\": \"1257L\",\n \"week1BasisFlag\": false,\n \"paymentMethodId\": 1,\n \"dni\": false,\n \"hiWiz\": false,\n \"safetyBoots\": true,\n \"digitalTacho\": false,\n \"wtdOptout\": false,\n \"isStudent\": false,\n \"canNotSendSmsEmail\": false,\n \"workerRating\": 8,\n \"costCentreId\": 3,\n \"workerTypeId\": 1,\n \"transportId\": 2,\n \"recruitmentSourceId\": 6,\n \"workRadius\": 25,\n \"minimumHourlyRate\": 12.21,\n \"minimumDailyRate\": 97.68,\n \"rtwShareCode\": \"W3K 9QP 7ZB\",\n \"subContractorId\": 55,\n \"bankDetails\": {\n \"bankAccountTypeId\": 1,\n \"accountName\": \"A Baker\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"01-02-03\",\n \"buildingSoc\": \"Skipton\"\n },\n \"additionalDetails\": {\n \"memo\": \"Prefers early shifts; will travel to Salford at short notice.\",\n \"experience\": \"Three years warehouse picking, counterbalance FLT since 2023.\",\n \"notes\": \"Registered in branch; documents seen in person.\",\n \"blacklistReason\": \"Left a shift without notice at Trafford Park, 14 August 2026.\",\n \"assessment\": \"Assessed on counterbalance FLT 12 May 2026 — competent, no retraining needed.\",\n \"bookingAvailabilityNotes\": \"Not available Thursdays; college day.\"\n },\n \"jobCategoryIds\": [\n 0\n ],\n \"vehicleCategoryIds\": [\n 0\n ],\n \"suitableAtSiteIds\": [\n 0\n ],\n \"notSuitableAtSiteIds\": [\n 0\n ],\n \"assessedAtSiteIds\": [\n 0\n ],\n \"bannedAtSiteIds\": [\n 0\n ]\n}" }, "description": "Registers a worker against one of your branches and returns the created record, including the worker number allocated from your agency's sequence.\n\nSeveral fields are conditionally required rather than always required:\n\n- **Bank details** are required for every payment method except Cheque. A building society account additionally requires the society name.\n- **SubContractorId** is required when the worker type is a subcontractor type.\n- **Starter-checklist statements** are ignored for tax forms that do not use them, and the tax code is overridden when the form is None or Not Required.\n\nUnset fields fall back to your agency's defaults — the default tax code, the default worker status, and weekly payment frequency. `BranchId` must be a branch you can access. At least one `JobCategoryIds` entry is required, and every one of them must belong to your agency. `VehicleCategoryIds` are ids from the platform Vehicle categories vocabulary — the same for every agency — and are optional, as are the four site lists, whose ids must be sites of your own agency.\n\n`BranchId` and the compliance documents are only settable here: UpdateWorker changes neither.\n\n`AdditionalDetails` — the free-text notes — is optional here and on UpdateWorker. Most workers are registered without any, and the record is only written when the object is sent.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get worker details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns a single worker with their tax details, bank details, compliance documents and job categories. Workers belonging to another agency, or registered against a branch the Recruso user behind your API app cannot access, return 404 rather than 403, so their existence is never disclosed. The same holds for every record a worker holds, on every worker operation.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a worker", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 4821,\n \"titleId\": 2,\n \"forename\": \"Alice\",\n \"surname\": \"Baker\",\n \"knownAs\": \"Ali\",\n \"initials\": \"AB\",\n \"birthDate\": \"1990-04-12\",\n \"genderId\": 2,\n \"maritalStatusId\": 1,\n \"ethnicOriginId\": 3,\n \"nationalityId\": 14,\n \"address1\": \"12 High Street\",\n \"address2\": \"Flat 2\",\n \"town\": \"Manchester\",\n \"county\": \"Greater Manchester\",\n \"country\": \"United Kingdom\",\n \"postalCode\": \"M1 1AA\",\n \"telephone1\": \"0161 496 0123\",\n \"mobile\": \"07700 900123\",\n \"email\": \"alice.baker@example.co.uk\",\n \"nextOfKinFullName\": \"Jane Baker\",\n \"nextOfKinContactNumber\": \"07700 900456\",\n \"nextOfKinEmailAddress\": \"jane.baker@example.co.uk\",\n \"niNumber\": \"AB123456C\",\n \"formId\": 1,\n \"niCategoryId\": 1,\n \"statementA\": true,\n \"statementB\": false,\n \"statementC\": false,\n \"noStatement\": false,\n \"employeeTaxCode\": \"1257L\",\n \"week1BasisFlag\": false,\n \"paymentMethodId\": 1,\n \"dni\": false,\n \"hiWiz\": false,\n \"safetyBoots\": true,\n \"digitalTacho\": false,\n \"wtdOptout\": false,\n \"isStudent\": false,\n \"canNotSendSmsEmail\": false,\n \"workerRating\": 8,\n \"costCentreId\": 3,\n \"workerTypeId\": 1,\n \"transportId\": 2,\n \"recruitmentSourceId\": 6,\n \"workRadius\": 25,\n \"minimumHourlyRate\": 12.21,\n \"minimumDailyRate\": 97.68,\n \"rtwShareCode\": \"W3K 9QP 7ZB\",\n \"subContractorId\": 55,\n \"bankDetails\": {\n \"bankAccountTypeId\": 1,\n \"accountName\": \"A Baker\",\n \"accountNumber\": \"12345678\",\n \"sortCode\": \"01-02-03\",\n \"buildingSoc\": \"Skipton\"\n },\n \"additionalDetails\": {\n \"memo\": \"Prefers early shifts; will travel to Salford at short notice.\",\n \"experience\": \"Three years warehouse picking, counterbalance FLT since 2023.\",\n \"notes\": \"Registered in branch; documents seen in person.\",\n \"blacklistReason\": \"Left a shift without notice at Trafford Park, 14 August 2026.\",\n \"assessment\": \"Assessed on counterbalance FLT 12 May 2026 — competent, no retraining needed.\",\n \"bookingAvailabilityNotes\": \"Not available Thursdays; college day.\"\n },\n \"jobCategoryIds\": [\n 0\n ],\n \"vehicleCategoryIds\": [\n 0\n ],\n \"suitableAtSiteIds\": [\n 0\n ],\n \"notSuitableAtSiteIds\": [\n 0\n ],\n \"assessedAtSiteIds\": [\n 0\n ],\n \"bannedAtSiteIds\": [\n 0\n ]\n}" }, "description": "Updates one worker in your own agency.\n\nThis 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. Send the complete record, not just the fields you are changing.\n\n**The same validation as CreateWorker applies** — bank details are required for every payment method except Cheque, a building society account also requires the society name, `SubContractorId` is required for a subcontractor worker type, the starter-checklist statements are cleared for tax forms that do not use them, and an unset tax code falls back to your agency's default. Every referenced id must exist and belong to your agency; one that does not returns 400.\n\nAt least one job category is required here too: an edit is a full replacement, so a worker cannot be saved with the list emptied.\n\nJob categories and vehicle categories are reconciled against the ids you send: those already held are kept as they are, those missing from the request are removed, and only new ones are added. The first job category is the worker's default. Reconciling rather than replacing is also what keeps a surviving vehicle category's original audit intact.\n\nThe four site lists — `SuitableAtSiteIds`, `NotSuitableAtSiteIds`, `AssessedAtSiteIds` and `BannedAtSiteIds` — are reconciled the same way, and are independent of one another: a site may appear on more than one. Every id you add must be a site of your own agency; one that is not returns 400 rather than disclosing that it exists elsewhere. A site the worker already holds on a list is not checked again, so it stays on that list even after your agency deletes the site.\n\n`VehicleCategoryIds` and the four site lists are exceptions to full replacement: omit one, or send it as null, and the list already held is left exactly as it is; send an empty list to clear it. Nothing historises them, and a client's ban lifted by an update that never mentioned it could not be recovered.\n\nSome of a worker's record is deliberately out of reach here. `BranchId`, `WorkerNumber`, `RegisteredDate` and the created-by audit are fixed at registration. Compliance documents and the worker's status are effective-dated history rather than current state, so they are not part of this request and are returned unchanged — a save of the worker's details can never delete a right-to-work record. A worker paid by cheque keeps any bank account already on file rather than having it deleted.\n\n`AdditionalDetails` — the free-text notes — is also an exception to full replacement: omit it and the notes on file are left alone, because nothing historises them and a silently cleared blacklist reason or assessment could not be recovered. Send the object to write them, and every field within it is replaced.\n\nA worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed. `modifiedBy` and `modifiedOn` are set from your credentials and the current UK local time; they are not taken from the request.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkerStatusHistory", "item": [ { "name": "Get a worker's status history", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/workers/:workerId/status-history", "host": [ "{{baseUrl}}" ], "path": [ "v1", "workers", ":workerId", "status-history" ], "variable": [ { "key": "workerId", "value": "", "description": "Required." } ] }, "description": "Returns every status a worker in your own agency has been moved to, newest first, with the reason recorded at the time.\n\nThe trail is append-only and read-only: an entry is written whenever the worker's status moves, and is never edited or removed afterwards. A worker who has never had a status change returns an empty list — the status assigned at registration is not a change. Moving a worker between statuses is not part of the published API yet, so the entries you see here were written elsewhere.\n\nThe list is not paged. A worker id belonging to another agency returns 404 rather than 403, so their existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] } ] }, { "name": "Lookups", "description": "The agency-configurable reference data every other call refers to by id. Each tag is a small CRUD surface your agency owns; read the Reference data & agency lookups concept page once and most of the family follows. Read each operation's own page for the parts that differ — three of these delete by flagging the record, the rest remove it outright, and not every one checks a name for duplicates.", "item": [ { "name": "ActivityTypes", "item": [ { "name": "List activity types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/activity-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "activity-types" ], "variable": [] }, "description": "Returns your agency's activity types, ordered by `activityTypeName`. Deleted records are excluded. An activity type groups the calls and visits your agency records against a client or a worker — a booking, a check-in, a sales call, a sales visit, a meeting.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create an activity type", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/activity-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "activity-types" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"activityTypeName\": \"\"\n}" }, "description": "Creates an activity type for your agency. An activity type groups the calls and visits your agency records against a client or a worker — a booking, a check-in, a sales call, a sales visit, a meeting.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get activity type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/activity-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "activity-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's activity types by id. An activity type groups the calls and visits your agency records against a client or a worker — a booking, a check-in, a sales call, a sales visit, a meeting.\n\nA deleted record returns 404 — it is retained in the database but is no longer readable through the API.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update an activity type", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/activity-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "activity-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"activityTypeName\": \"\"\n}" }, "description": "Updates one of your agency's activity types. An activity type groups the calls and visits your agency records against a client or a worker — a booking, a check-in, a sales call, a sales visit, a meeting.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete an activity type", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/activity-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "activity-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Marks one of your agency's activity types as deleted.\n\nThe record is retained in the database but stops appearing in list and get-by-id responses. There is no restore endpoint. Its name is released, so a new record may reuse it.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "AvailabilityStatuses", "item": [ { "name": "List availability statuses", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/availability-statuses", "host": [ "{{baseUrl}}" ], "path": [ "v1", "availability-statuses" ], "variable": [] }, "description": "Returns your agency's availability statuses, ordered by `availabilityStatusName`. An availability status marks what a worker is doing on a given day — available, on holiday, at the doctor, on paternity leave.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create an availability status", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/availability-statuses", "host": [ "{{baseUrl}}" ], "path": [ "v1", "availability-statuses" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"availabilityStatusName\": \"\",\n \"awrSpecific\": false,\n \"displayInWorkerApp\": false,\n \"displayTextInWorkerApp\": \"\"\n}" }, "description": "Creates an availability status for your agency. An availability status marks what a worker is doing on a given day — available, on holiday, at the doctor, on paternity leave.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get availability status details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/availability-statuses/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "availability-statuses", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's availability statuses by id. An availability status marks what a worker is doing on a given day — available, on holiday, at the doctor, on paternity leave.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update an availability status", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/availability-statuses/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "availability-statuses", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"availabilityStatusName\": \"\",\n \"awrSpecific\": false,\n \"displayInWorkerApp\": false,\n \"displayTextInWorkerApp\": \"\"\n}" }, "description": "Updates one of your agency's availability statuses. An availability status marks what a worker is doing on a given day — available, on holiday, at the doctor, on paternity leave.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nOnce any availability entry in your agency uses the status, its name and its `awrSpecific` flag can no longer change, so an entry cannot be moved into or out of the statuses that affect a worker's AWR parity after it was recorded. A change to either returns 400, naming the field; the other fields stay editable. A name counts as changed when it differs at all once surrounding spaces are removed, a change of case included; sending the stored name back unchanged is never refused.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete an availability status", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/availability-statuses/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "availability-statuses", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Permanently deletes one of your agency's availability statuses.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "AwrAlertRules", "item": [ { "name": "List AWR alert rules", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/awr-alert-rules", "host": [ "{{baseUrl}}" ], "path": [ "v1", "awr-alert-rules" ], "variable": [] }, "description": "Returns your agency's AWR alert rules, ordered by `weekThreshold`. Under the Agency Workers Regulations a worker reaches parity in week 12, and these rules decide which of the weeks up to that point your agency is alerted in — a single week, or every week until parity is reached.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create an AWR alert rule", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/awr-alert-rules", "host": [ "{{baseUrl}}" ], "path": [ "v1", "awr-alert-rules" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"weekThreshold\": 0,\n \"isActive\": false\n}" }, "description": "Creates an AWR alert rule for your agency. Under the Agency Workers Regulations a worker reaches parity in week 12, and these rules decide which of the weeks up to that point your agency is alerted in — a single week, or every week until parity is reached.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get AWR alert rule details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/awr-alert-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "awr-alert-rules", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's AWR alert rules by id. Under the Agency Workers Regulations a worker reaches parity in week 12, and these rules decide which of the weeks up to that point your agency is alerted in — a single week, or every week until parity is reached.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update an AWR alert rule", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/awr-alert-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "awr-alert-rules", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"weekThreshold\": 0,\n \"isActive\": false\n}" }, "description": "Updates one of your agency's AWR alert rules. Under the Agency Workers Regulations a worker reaches parity in week 12, and these rules decide which of the weeks up to that point your agency is alerted in — a single week, or every week until parity is reached.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete an AWR alert rule", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/awr-alert-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "awr-alert-rules", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one of your agency's AWR alert rules.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "BankHolidays", "item": [ { "name": "List bank holidays", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/bank-holidays", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bank-holidays" ], "variable": [] }, "description": "Returns your agency's bank holidays, ordered by `bankHolidayDate`. These are the UK bank holiday dates. Recruso supplies them and refreshes them each year from the government's list, and hours worked on one are expected to be paid at the bank holiday rate.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a bank holiday", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/bank-holidays", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bank-holidays" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"bankHolidayDate\": \"\"\n}" }, "description": "Creates a bank holiday for your agency. These are the UK bank holiday dates. Recruso supplies them and refreshes them each year from the government's list, and hours worked on one are expected to be paid at the bank holiday rate.\n\nNames are not checked for uniqueness, so the same name can be used more than once.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get bank holiday details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/bank-holidays/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bank-holidays", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's bank holidays by id. These are the UK bank holiday dates. Recruso supplies them and refreshes them each year from the government's list, and hours worked on one are expected to be paid at the bank holiday rate.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a bank holiday", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/bank-holidays/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bank-holidays", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"bankHolidayDate\": \"\"\n}" }, "description": "Updates one of your agency's bank holidays. These are the UK bank holiday dates. Recruso supplies them and refreshes them each year from the government's list, and hours worked on one are expected to be paid at the bank holiday rate.\n\nSend the complete record: the fields you supply replace the stored values.\n\nNames are not checked for uniqueness.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a bank holiday", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/bank-holidays/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "bank-holidays", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one of your agency's bank holidays.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "Compliance", "item": [ { "name": "List compliance items", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/compliance", "host": [ "{{baseUrl}}" ], "path": [ "v1", "compliance" ], "variable": [] }, "description": "Returns your agency's compliance items, ordered by `complianceName`. A compliance item is a record your agency holds against a worker, and it may or may not carry a validity date.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a compliance item", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/compliance", "host": [ "{{baseUrl}}" ], "path": [ "v1", "compliance" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"complianceName\": \"\",\n \"displayInSelfRegistration\": false\n}" }, "description": "Creates a compliance item for your agency. A compliance item is a record your agency holds against a worker, and it may or may not carry a validity date.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get compliance item details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/compliance/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "compliance", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's compliance items by id. A compliance item is a record your agency holds against a worker, and it may or may not carry a validity date.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a compliance item", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/compliance/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "compliance", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"complianceName\": \"\",\n \"displayInSelfRegistration\": false\n}" }, "description": "Updates one of your agency's compliance items. A compliance item is a record your agency holds against a worker, and it may or may not carry a validity date.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a compliance item", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/compliance/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "compliance", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Permanently deletes one of your agency's compliance items.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "DayRateRules", "item": [ { "name": "List day rate rules", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/day-rate-rules", "host": [ "{{baseUrl}}" ], "path": [ "v1", "day-rate-rules" ], "variable": [] }, "description": "Returns your agency's day rate rules, ordered by `dayRateRuleName`. A day rate rule sets the work hours, break time, overtime and associated rates for one shift.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a day rate rule", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/day-rate-rules", "host": [ "{{baseUrl}}" ], "path": [ "v1", "day-rate-rules" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"dayRateRuleName\": \"\",\n \"shiftHours\": 0,\n \"shiftRateTypeId\": 0,\n \"breakHours\": 0,\n \"overtimeAfterHours\": 0,\n \"overtimeRateTypeId\": 0,\n \"noOvertime\": false\n}" }, "description": "Creates a day rate rule for your agency. A day rate rule sets the work hours, break time, overtime and associated rates for one shift.\n\nNames are not checked for uniqueness, so the same name can be used more than once.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get day rate rule details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/day-rate-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "day-rate-rules", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's day rate rules by id. A day rate rule sets the work hours, break time, overtime and associated rates for one shift.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a day rate rule", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/day-rate-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "day-rate-rules", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"dayRateRuleName\": \"\",\n \"shiftHours\": 0,\n \"shiftRateTypeId\": 0,\n \"breakHours\": 0,\n \"overtimeAfterHours\": 0,\n \"overtimeRateTypeId\": 0,\n \"noOvertime\": false\n}" }, "description": "Updates one of your agency's day rate rules. A day rate rule sets the work hours, break time, overtime and associated rates for one shift.\n\nSend the complete record: the fields you supply replace the stored values.\n\nNames are not checked for uniqueness.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a day rate rule", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/day-rate-rules/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "day-rate-rules", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one of your agency's day rate rules.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "JobCategories", "item": [ { "name": "List job categories", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/job-categories", "host": [ "{{baseUrl}}" ], "path": [ "v1", "job-categories" ], "variable": [] }, "description": "Returns your agency's job categories, ordered by `jobCategoryName`. Deleted records are excluded. A job category is a skill a worker can be recorded as having.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a job category", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/job-categories", "host": [ "{{baseUrl}}" ], "path": [ "v1", "job-categories" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"jobCategoryName\": \"\",\n \"displayInSelfRegistration\": false\n}" }, "description": "Creates a job category for your agency. A job category is a skill a worker can be recorded as having.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get job category details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/job-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "job-categories", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's job categories by id. A job category is a skill a worker can be recorded as having.\n\nA deleted record returns 404 — it is retained in the database but is no longer readable through the API.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a job category", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/job-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "job-categories", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"jobCategoryName\": \"\",\n \"displayInSelfRegistration\": false\n}" }, "description": "Updates one of your agency's job categories. A job category is a skill a worker can be recorded as having.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a job category", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/job-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "job-categories", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Marks one of your agency's job categories as deleted.\n\nThe record is retained in the database but stops appearing in list and get-by-id responses. There is no restore endpoint. Its name is released, so a new record may reuse it.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "KeyInformationForPayeWorkers", "item": [ { "name": "Get PAYE key information document details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-paye-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-paye-workers" ], "variable": [] }, "description": "Returns one of your agency's PAYE key information documents by id. Nothing calculates from these values — they are reproduced as text in reports, which is the whole of what the document is for.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a PAYE key information document", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-paye-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-paye-workers" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"employerName\": \"\",\n \"contractType\": \"\",\n \"paymentFrom\": \"\",\n \"expectedPayRate\": \"\",\n \"deductionFromPay\": \"\",\n \"extraDeductionFromPay\": \"\",\n \"feesForServices\": \"\",\n \"holidayEntitlementAndPay\": \"\",\n \"additionalBenefits\": \"\",\n \"examplePayRate\": \"\",\n \"deductionFromWages\": \"\",\n \"extraDeductionFromWages\": \"\",\n \"exampleFeesForService\": \"\",\n \"exampleNetHomeTakePay\": \"\"\n}" }, "description": "Updates one of your agency's PAYE key information documents. Nothing calculates from these values — they are reproduced as text in reports, which is the whole of what the document is for.\n\nSend the complete record: the fields you supply replace the stored values.\n\nNames are not checked for uniqueness.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a PAYE key information document", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-paye-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-paye-workers" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"employerName\": \"\",\n \"contractType\": \"\",\n \"paymentFrom\": \"\",\n \"expectedPayRate\": \"\",\n \"deductionFromPay\": \"\",\n \"extraDeductionFromPay\": \"\",\n \"feesForServices\": \"\",\n \"holidayEntitlementAndPay\": \"\",\n \"additionalBenefits\": \"\",\n \"examplePayRate\": \"\",\n \"deductionFromWages\": \"\",\n \"extraDeductionFromWages\": \"\",\n \"exampleFeesForService\": \"\",\n \"exampleNetHomeTakePay\": \"\"\n}" }, "description": "Creates a PAYE key information document for your agency. Nothing calculates from these values — they are reproduced as text in reports, which is the whole of what the document is for.\n\nNames are not checked for uniqueness, so the same name can be used more than once.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a PAYE key information document", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-paye-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-paye-workers" ], "variable": [] }, "description": "Permanently deletes one of your agency's PAYE key information documents.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "KeyInformationForSubContractorWorkers", "item": [ { "name": "Get subcontractor key information document details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-subcontractor-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-subcontractor-workers" ], "variable": [] }, "description": "Returns one of your agency's subcontractor key information documents by id. Nothing calculates from these values — they are reproduced as text in reports, which is the whole of what the document is for.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a subcontractor key information document", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-subcontractor-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-subcontractor-workers" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"contractType\": \"\",\n \"businessConnectionWithSubContractor\": \"\",\n \"expectedGrossPayRate\": \"\",\n \"deductionFromSubContractorIncome\": \"\",\n \"otherDeductionFromSubContractorIncome\": \"\",\n \"expectedPayRate\": \"\",\n \"deductionFromWage\": \"\",\n \"extraDeductionFromWage\": \"\",\n \"feesForServices\": \"\",\n \"holidayEntitlementAndPay\": \"\",\n \"additionalBenefits\": \"\",\n \"exampleGrossPayRateToSubContractor\": \"\",\n \"deductionFromSubContractor\": \"\",\n \"extraDeductionFromSubContractorIncome\": \"\",\n \"examplePayRate\": \"\",\n \"deductionFromWorkersPay\": \"\",\n \"extraDeductionFromWorkersPay\": \"\",\n \"extraFeesForServices\": \"\",\n \"netTakeHomePay\": \"\",\n \"exampleGrossPayRateToWorker\": \"\",\n \"deductionFromWorker\": \"\",\n \"extraDeductionFromWorkerIncome\": \"\",\n \"examplePayRateSubContractor\": \"\",\n \"deductionFromSubContractorPay\": \"\",\n \"extraDeductionFromSubContractorPay\": \"\",\n \"extraFeesForServicesForSubContractor\": \"\",\n \"netTakeHomePaySubContractor\": \"\"\n}" }, "description": "Updates one of your agency's subcontractor key information documents. Nothing calculates from these values — they are reproduced as text in reports, which is the whole of what the document is for.\n\nSend the complete record: the fields you supply replace the stored values.\n\nNames are not checked for uniqueness.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a subcontractor key information document", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-subcontractor-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-subcontractor-workers" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"contractType\": \"\",\n \"businessConnectionWithSubContractor\": \"\",\n \"expectedGrossPayRate\": \"\",\n \"deductionFromSubContractorIncome\": \"\",\n \"otherDeductionFromSubContractorIncome\": \"\",\n \"expectedPayRate\": \"\",\n \"deductionFromWage\": \"\",\n \"extraDeductionFromWage\": \"\",\n \"feesForServices\": \"\",\n \"holidayEntitlementAndPay\": \"\",\n \"additionalBenefits\": \"\",\n \"exampleGrossPayRateToSubContractor\": \"\",\n \"deductionFromSubContractor\": \"\",\n \"extraDeductionFromSubContractorIncome\": \"\",\n \"examplePayRate\": \"\",\n \"deductionFromWorkersPay\": \"\",\n \"extraDeductionFromWorkersPay\": \"\",\n \"extraFeesForServices\": \"\",\n \"netTakeHomePay\": \"\",\n \"exampleGrossPayRateToWorker\": \"\",\n \"deductionFromWorker\": \"\",\n \"extraDeductionFromWorkerIncome\": \"\",\n \"examplePayRateSubContractor\": \"\",\n \"deductionFromSubContractorPay\": \"\",\n \"extraDeductionFromSubContractorPay\": \"\",\n \"extraFeesForServicesForSubContractor\": \"\",\n \"netTakeHomePaySubContractor\": \"\"\n}" }, "description": "Creates a subcontractor key information document for your agency. Nothing calculates from these values — they are reproduced as text in reports, which is the whole of what the document is for.\n\nNames are not checked for uniqueness, so the same name can be used more than once.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a subcontractor key information document", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/key-information-for-subcontractor-workers", "host": [ "{{baseUrl}}" ], "path": [ "v1", "key-information-for-subcontractor-workers" ], "variable": [] }, "description": "Permanently deletes one of your agency's subcontractor key information documents.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "LoggingHours", "item": [ { "name": "List logging hours entries", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/logging-hours", "host": [ "{{baseUrl}}" ], "path": [ "v1", "logging-hours" ], "variable": [] }, "description": "Returns your agency's logging hours entries, ordered by `loggingHoursName`. A logging hours entry is one of the ways a worker can log their hours — a clock card, a block timesheet, a digi card, a hand scanner, a timesheet, the app.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a logging hours entry", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/logging-hours", "host": [ "{{baseUrl}}" ], "path": [ "v1", "logging-hours" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"loggingHourName\": \"\"\n}" }, "description": "Creates a logging hours entry for your agency. A logging hours entry is one of the ways a worker can log their hours — a clock card, a block timesheet, a digi card, a hand scanner, a timesheet, the app.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get logging hours entry details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/logging-hours/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "logging-hours", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's logging hours entries by id. A logging hours entry is one of the ways a worker can log their hours — a clock card, a block timesheet, a digi card, a hand scanner, a timesheet, the app.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a logging hours entry", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/logging-hours/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "logging-hours", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"loggingHourName\": \"\"\n}" }, "description": "Updates one of your agency's logging hours entries. A logging hours entry is one of the ways a worker can log their hours — a clock card, a block timesheet, a digi card, a hand scanner, a timesheet, the app.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a logging hours entry", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/logging-hours/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "logging-hours", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one of your agency's logging hours entries.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "RateTypes", "item": [ { "name": "List rate types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/rate-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-types" ], "variable": [] }, "description": "Returns your agency's rate types, ordered by `rateTypeName`. A rate type is one of the rates a worker's hours can be paid at — basic, overtime, Saturday, Sunday, basic nights, night out, and pre- and post-tax expenses.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a rate type", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/rate-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-types" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"rateTypeName\": \"\",\n \"isExpense\": false,\n \"calculateInAverageRate\": false,\n \"priorityOrder\": 0,\n \"sagePayElementId\": 0,\n \"isExpenseTaxable\": false,\n \"primaryRateTypeId\": 0,\n \"marginRate\": 0,\n \"isVatable\": false\n}" }, "description": "Creates a rate type for your agency. A rate type is one of the rates a worker's hours can be paid at — basic, overtime, Saturday, Sunday, basic nights, night out, and pre- and post-tax expenses.\n\nNames are not checked for uniqueness, so the same name can be used more than once.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get rate type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/rate-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's rate types by id. A rate type is one of the rates a worker's hours can be paid at — basic, overtime, Saturday, Sunday, basic nights, night out, and pre- and post-tax expenses.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a rate type", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/rate-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"rateTypeName\": \"\",\n \"isExpense\": false,\n \"calculateInAverageRate\": false,\n \"priorityOrder\": 0,\n \"sagePayElementId\": 0,\n \"isExpenseTaxable\": false,\n \"primaryRateTypeId\": 0,\n \"marginRate\": 0,\n \"isVatable\": false\n}" }, "description": "Updates one of your agency's rate types. A rate type is one of the rates a worker's hours can be paid at — basic, overtime, Saturday, Sunday, basic nights, night out, and pre- and post-tax expenses.\n\nSend the complete record: the fields you supply replace the stored values.\n\nNames are not checked for uniqueness.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a rate type", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/rate-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "rate-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one of your agency's rate types.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "ReceivingHours", "item": [ { "name": "List receiving hours entries", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/receiving-hours", "host": [ "{{baseUrl}}" ], "path": [ "v1", "receiving-hours" ], "variable": [] }, "description": "Returns your agency's receiving hours entries, ordered by `receivingHoursName`. A receiving hours entry is how a client prefers to receive its workers' hours — a block timesheet, email, the portal, post, a text message, or from the workers themselves.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a receiving hours entry", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/receiving-hours", "host": [ "{{baseUrl}}" ], "path": [ "v1", "receiving-hours" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"receivingHourName\": \"\"\n}" }, "description": "Creates a receiving hours entry for your agency. A receiving hours entry is how a client prefers to receive its workers' hours — a block timesheet, email, the portal, post, a text message, or from the workers themselves.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get receiving hours entry details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/receiving-hours/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "receiving-hours", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's receiving hours entries by id. A receiving hours entry is how a client prefers to receive its workers' hours — a block timesheet, email, the portal, post, a text message, or from the workers themselves.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a receiving hours entry", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/receiving-hours/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "receiving-hours", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"receivingHourName\": \"\"\n}" }, "description": "Updates one of your agency's receiving hours entries. A receiving hours entry is how a client prefers to receive its workers' hours — a block timesheet, email, the portal, post, a text message, or from the workers themselves.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a receiving hours entry", "request": { "method": "DELETE", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/receiving-hours/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "receiving-hours", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Permanently deletes one of your agency's receiving hours entries.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "RecruitmentSources", "item": [ { "name": "List recruitment sources", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/recruitment-sources", "host": [ "{{baseUrl}}" ], "path": [ "v1", "recruitment-sources" ], "variable": [] }, "description": "Returns your agency's recruitment sources, ordered by `recruitmentSourceName`. A recruitment source is how a worker heard about your agency — a job board, Indeed, Facebook, a newspaper, a friend, a cold call, a mail shot, an employment exchange.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a recruitment source", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/recruitment-sources", "host": [ "{{baseUrl}}" ], "path": [ "v1", "recruitment-sources" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"recruitmentSourceName\": \"\"\n}" }, "description": "Creates a recruitment source for your agency. A recruitment source is how a worker heard about your agency — a job board, Indeed, Facebook, a newspaper, a friend, a cold call, a mail shot, an employment exchange.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get recruitment source details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/recruitment-sources/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "recruitment-sources", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's recruitment sources by id. A recruitment source is how a worker heard about your agency — a job board, Indeed, Facebook, a newspaper, a friend, a cold call, a mail shot, an employment exchange.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a recruitment source", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/recruitment-sources/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "recruitment-sources", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"recruitmentSourceName\": \"\"\n}" }, "description": "Updates one of your agency's recruitment sources. A recruitment source is how a worker heard about your agency — a job board, Indeed, Facebook, a newspaper, a friend, a cold call, a mail shot, an employment exchange.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a recruitment source", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/recruitment-sources/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "recruitment-sources", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Permanently deletes one of your agency's recruitment sources.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "Shifts", "item": [ { "name": "List shifts", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/shifts", "host": [ "{{baseUrl}}" ], "path": [ "v1", "shifts" ], "variable": [] }, "description": "Returns your agency's shifts, ordered by `shiftName`. Deleted records are excluded. A shift is a working pattern your agency runs — day, noon, night, all hours.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a shift", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/shifts", "host": [ "{{baseUrl}}" ], "path": [ "v1", "shifts" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"shiftName\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\"\n}" }, "description": "Creates a shift for your agency. A shift is a working pattern your agency runs — day, noon, night, all hours.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get shift details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/shifts/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "shifts", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's shifts by id. A shift is a working pattern your agency runs — day, noon, night, all hours.\n\nA deleted record returns 404 — it is retained in the database but is no longer readable through the API.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a shift", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/shifts/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "shifts", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"shiftName\": \"\",\n \"startTime\": \"\",\n \"endTime\": \"\"\n}" }, "description": "Updates one of your agency's shifts. A shift is a working pattern your agency runs — day, noon, night, all hours.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a shift", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/shifts/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "shifts", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Marks one of your agency's shifts as deleted.\n\nThe record is retained in the database but stops appearing in list and get-by-id responses. There is no restore endpoint. Its name is released, so a new record may reuse it.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "SmsTemplates", "item": [ { "name": "List SMS templates", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/sms-templates", "host": [ "{{baseUrl}}" ], "path": [ "v1", "sms-templates" ], "variable": [] }, "description": "Returns your agency's SMS templates, ordered by `templateName`. Recruso sends SMS and WhatsApp messages on your agency's behalf, and a template saves writing the same message every time.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create an SMS template", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/sms-templates", "host": [ "{{baseUrl}}" ], "path": [ "v1", "sms-templates" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"templateName\": \"\",\n \"templateDescription\": \"\"\n}" }, "description": "Creates an SMS template for your agency. Recruso sends SMS and WhatsApp messages on your agency's behalf, and a template saves writing the same message every time.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get SMS template details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/sms-templates/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "sms-templates", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's SMS templates by id. Recruso sends SMS and WhatsApp messages on your agency's behalf, and a template saves writing the same message every time.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update an SMS template", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/sms-templates/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "sms-templates", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"templateName\": \"\",\n \"templateDescription\": \"\"\n}" }, "description": "Updates one of your agency's SMS templates. Recruso sends SMS and WhatsApp messages on your agency's behalf, and a template saves writing the same message every time.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete an SMS template", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/sms-templates/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "sms-templates", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Permanently deletes one of your agency's SMS templates.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "Transports", "item": [ { "name": "List transport options", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/transports", "host": [ "{{baseUrl}}" ], "path": [ "v1", "transports" ], "variable": [] }, "description": "Returns your agency's transport options, ordered by `transportName`. A transport option is how a worker gets to a job — bus, bicycle, public transport.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a transport option", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/transports", "host": [ "{{baseUrl}}" ], "path": [ "v1", "transports" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"transportName\": \"\"\n}" }, "description": "Creates a transport option for your agency. A transport option is how a worker gets to a job — bus, bicycle, public transport.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get transport option details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/transports/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "transports", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's transport options by id. A transport option is how a worker gets to a job — bus, bicycle, public transport.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a transport option", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/transports/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "transports", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"transportName\": \"\"\n}" }, "description": "Updates one of your agency's transport options. A transport option is how a worker gets to a job — bus, bicycle, public transport.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Delete a transport option", "request": { "method": "DELETE", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/transports/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "transports", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0\n}" }, "description": "Permanently deletes one of your agency's transport options.\n\nThe row is removed rather than flagged, so this cannot be undone and there is no restore endpoint. Anything still referencing the record keeps the raw id it was given.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] }, { "name": "WorkDetailLabels", "item": [ { "name": "List work detail labels", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/work-detail-labels", "host": [ "{{baseUrl}}" ], "path": [ "v1", "work-detail-labels" ], "variable": [] }, "description": "Returns your agency's work detail labels, ordered by `workDetailId`. Work detail labels rename the work-detail fields on a worker record. The five that can be relabelled are DNI, HiWiz, special rates, safety boots and digital tacho.\n\nThe response is not paged.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Create a work detail label", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/work-detail-labels", "host": [ "{{baseUrl}}" ], "path": [ "v1", "work-detail-labels" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"dniLabel\": \"\",\n \"hiVizLabel\": \"\",\n \"specialRatesLabel\": \"\",\n \"safetyBootsLabel\": \"\",\n \"digitalTachoLabel\": \"\"\n}" }, "description": "Creates a work detail label for your agency. Work detail labels rename the work-detail fields on a worker record. The five that can be relabelled are DNI, HiWiz, special rates, safety boots and digital tacho.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400 rather than creating a duplicate.\n\nReturns 201 with the created record.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Get work detail label details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/work-detail-labels/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "work-detail-labels", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one of your agency's work detail labels by id. Work detail labels rename the work-detail fields on a worker record. The five that can be relabelled are DNI, HiWiz, special rates, safety boots and digital tacho.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] }, { "name": "Update a work detail label", "request": { "method": "PUT", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/work-detail-labels/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "work-detail-labels", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "body": { "mode": "raw", "raw": "{\n \"id\": 0,\n \"dniLabel\": \"\",\n \"hiVizLabel\": \"\",\n \"specialRatesLabel\": \"\",\n \"safetyBootsLabel\": \"\",\n \"digitalTachoLabel\": \"\"\n}" }, "description": "Updates one of your agency's work detail labels. Work detail labels rename the work-detail fields on a worker record. The five that can be relabelled are DNI, HiWiz, special rates, safety boots and digital tacho.\n\nSend the complete record: the fields you supply replace the stored values.\n\nThe name must not already be in use by another of your agency's records; a clash returns 400. The record's own current name is allowed.\n\nYou only ever see and change your own agency's records; there is no owner id on the request, and an id belonging to another agency returns 404 rather than 403 so that its existence is never disclosed.\n\n**Access.** Requires a client-credentials access token. Tokens issued through the interactive user login are rejected." }, "response": [] } ] } ] }, { "name": "Reference data", "description": "Platform-wide read-only vocabularies — titles, genders, nationalities, worker types and the rest — identical for every agency. A worker or client record refers to these by id, so they are the values you need before you can create one. Distinct from Lookups, which your agency owns and configures.", "item": [ { "name": "BankAccountTypes", "item": [ { "name": "List bank account types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/bank-account-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "bank-account-types" ], "variable": [] }, "description": "Returns every bank account type the platform publishes. Distinguishes a bank account from a building society account. You need one when you record a worker's bank details.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a bank account type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get bank account type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/bank-account-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "bank-account-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one bank account type by id. Distinguishes a bank account from a building society account. You need one when you record a worker's bank details.\n\nBank account types are platform-wide, so an id means the same bank account type for every agency.\n\nAn id that does not match a bank account type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "ClientInvoiceTypes", "item": [ { "name": "List client invoice types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/client-invoice-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "client-invoice-types" ], "variable": [] }, "description": "Returns every client invoice type the platform publishes. The client endpoints take this vocabulary by name rather than by id: `clientInvoiceType` on create and update a client is matched against these names, and an unrecognised name returns 400 listing the accepted values.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a client invoice type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get client invoice type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/client-invoice-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "client-invoice-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one client invoice type by id. The client endpoints take this vocabulary by name rather than by id: `clientInvoiceType` on create and update a client is matched against these names, and an unrecognised name returns 400 listing the accepted values.\n\nClient invoice types are platform-wide, so an id means the same client invoice type for every agency.\n\nAn id that does not match a client invoice type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "ClientStatusTypes", "item": [ { "name": "List client status types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/client-status-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "client-status-types" ], "variable": [] }, "description": "Returns every client status type the platform publishes. The statuses a client can be held under — `Archived`, `Current`, `Hot`, `On hold` and `Seasonal`. A client can carry more than one, and this is the primary status vocabulary.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a client status type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get client status type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/client-status-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "client-status-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one client status type by id. The statuses a client can be held under — `Archived`, `Current`, `Hot`, `On hold` and `Seasonal`. A client can carry more than one, and this is the primary status vocabulary.\n\nClient status types are platform-wide, so an id means the same client status type for every agency.\n\nAn id that does not match a client status type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "ClientTypes", "item": [ { "name": "List client types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/client-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "client-types" ], "variable": [] }, "description": "Returns every client type the platform publishes. Recruso separates live clients from prospective ones. The client endpoints resolve the type named `Live` themselves and the lead endpoints resolve their own, so you never send a client type on a request.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a client type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get client type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/client-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "client-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one client type by id. Recruso separates live clients from prospective ones. The client endpoints resolve the type named `Live` themselves and the lead endpoints resolve their own, so you never send a client type on a request.\n\nClient types are platform-wide, so an id means the same client type for every agency.\n\nAn id that does not match a client type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "DrivingConvictionCodes", "item": [ { "name": "List driving conviction codes", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/driving-conviction-codes", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "driving-conviction-codes" ], "variable": [] }, "description": "Returns every driving conviction code the platform publishes. The DVLA endorsement codes that can be recorded against a driver.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a driving conviction code id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get driving conviction code details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/driving-conviction-codes/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "driving-conviction-codes", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one driving conviction code by id. The DVLA endorsement codes that can be recorded against a driver.\n\nDriving conviction codes are platform-wide, so an id means the same driving conviction code for every agency.\n\nAn id that does not match a driving conviction code returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "EthnicOrigins", "item": [ { "name": "List ethnic origins", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/ethnic-origins", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "ethnic-origins" ], "variable": [] }, "description": "Returns every ethnic origin the platform publishes. A worker's ethnic origin — African, Asian, European and the rest.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a ethnic origin — `ethnicOriginId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get ethnic origin details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/ethnic-origins/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "ethnic-origins", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one ethnic origin by id. A worker's ethnic origin — African, Asian, European and the rest.\n\nEthnic origins are platform-wide, so an id means the same ethnic origin for every agency.\n\nAn id that does not match a ethnic origin returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "FormsProvided", "item": [ { "name": "List forms provided", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/forms-provided", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "forms-provided" ], "variable": [] }, "description": "Returns every form provided the platform publishes. Part of a worker's tax details: which starter form the worker provided. The values are `None`, `Not Required`, `P45` and `Starter Checklist (P46)`.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a form provided id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get form provided details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/forms-provided/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "forms-provided", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one form provided by id. Part of a worker's tax details: which starter form the worker provided. The values are `None`, `Not Required`, `P45` and `Starter Checklist (P46)`.\n\nForms provided are platform-wide, so an id means the same form provided for every agency.\n\nAn id that does not match a form provided returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "Genders", "item": [ { "name": "List genders", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/genders", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "genders" ], "variable": [] }, "description": "Returns every gender the platform publishes. A worker's or a candidate's gender.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a gender — `genderId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get gender details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/genders/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "genders", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one gender by id. A worker's or a candidate's gender.\n\nGenders are platform-wide, so an id means the same gender for every agency.\n\nAn id that does not match a gender returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "HolidayAccrualMethods", "item": [ { "name": "List holiday accrual methods", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/holiday-accrual-methods", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "holiday-accrual-methods" ], "variable": [] }, "description": "Returns every holiday accrual method the platform publishes. How a worker's holiday entitlement accrues. Recruso sets this for your agency when it is onboarded, so this is published to be read rather than chosen.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a holiday accrual method — `holidayAccrualMethodId` on UpdateAgency.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get holiday accrual method details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/holiday-accrual-methods/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "holiday-accrual-methods", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one holiday accrual method by id. How a worker's holiday entitlement accrues. Recruso sets this for your agency when it is onboarded, so this is published to be read rather than chosen.\n\nHoliday accrual methods are platform-wide, so an id means the same holiday accrual method for every agency.\n\nAn id that does not match a holiday accrual method returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "HolidayCalculationMethods", "item": [ { "name": "List holiday calculation methods", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/holiday-calculation-methods", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "holiday-calculation-methods" ], "variable": [] }, "description": "Returns every holiday calculation method the platform publishes. How holiday pay is calculated. Recruso sets this for your agency when it is onboarded, so this is published to be read rather than chosen.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a holiday calculation method id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get holiday calculation method details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/holiday-calculation-methods/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "holiday-calculation-methods", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one holiday calculation method by id. How holiday pay is calculated. Recruso sets this for your agency when it is onboarded, so this is published to be read rather than chosen.\n\nHoliday calculation methods are platform-wide, so an id means the same holiday calculation method for every agency.\n\nAn id that does not match a holiday calculation method returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "HolidayTypes", "item": [ { "name": "List holiday types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/holiday-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "holiday-types" ], "variable": [] }, "description": "Returns every holiday type the platform publishes. The kind of holiday a worker can book. Recruso supports a full day and a half day.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a holiday type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get holiday type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/holiday-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "holiday-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one holiday type by id. The kind of holiday a worker can book. Recruso supports a full day and a half day.\n\nHoliday types are platform-wide, so an id means the same holiday type for every agency.\n\nAn id that does not match a holiday type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "InterviewStatuses", "item": [ { "name": "List interview statuses", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/interview-statuses", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "interview-statuses" ], "variable": [] }, "description": "Returns every interview status the platform publishes. Used by Recruso's permanent-recruitment application rather than by temporary recruitment. Nothing on this API consumes it.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a interview status id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get interview status details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/interview-statuses/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "interview-statuses", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one interview status by id. Used by Recruso's permanent-recruitment application rather than by temporary recruitment. Nothing on this API consumes it.\n\nInterview statuses are platform-wide, so an id means the same interview status for every agency.\n\nAn id that does not match a interview status returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "InvoiceMethods", "item": [ { "name": "List invoice methods", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/invoice-methods", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "invoice-methods" ], "variable": [] }, "description": "Returns every invoice method the platform publishes. How a client wants its invoices grouped. The values are `Cost Centre`, `Employees`, `Job Category`, `PO Number Day/Rate`, `PO Order Number` and `Standard`.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a invoice method — `invoiceMethodId` on CreateSite and `invoiceMethodId` on UpdateSite.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get invoice method details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/invoice-methods/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "invoice-methods", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one invoice method by id. How a client wants its invoices grouped. The values are `Cost Centre`, `Employees`, `Job Category`, `PO Number Day/Rate`, `PO Order Number` and `Standard`.\n\nInvoice methods are platform-wide, so an id means the same invoice method for every agency.\n\nAn id that does not match a invoice method returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "MaritalStatuses", "item": [ { "name": "List marital statuses", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/marital-statuses", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "marital-statuses" ], "variable": [] }, "description": "Returns every marital status the platform publishes. A worker's marital status.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a marital status — `maritalStatusId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get marital status details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/marital-statuses/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "marital-statuses", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one marital status by id. A worker's marital status.\n\nMarital statuses are platform-wide, so an id means the same marital status for every agency.\n\nAn id that does not match a marital status returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "Nationalities", "item": [ { "name": "List nationalities", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/nationalities", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "nationalities" ], "variable": [] }, "description": "Returns every nationality the platform publishes. A worker's nationality.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a nationality — `nationalityId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get nationality details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/nationalities/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "nationalities", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one nationality by id. A worker's nationality.\n\nNationalities are platform-wide, so an id means the same nationality for every agency.\n\nAn id that does not match a nationality returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "NiCategories", "item": [ { "name": "List National Insurance categories", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/ni-categories", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "ni-categories" ], "variable": [] }, "description": "Returns every National Insurance category the platform publishes. The HMRC National Insurance category letter a worker is paid under.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a National Insurance category — `niCategoryId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get National Insurance category details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/ni-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "ni-categories", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one National Insurance category by id. The HMRC National Insurance category letter a worker is paid under.\n\nNational Insurance categories are platform-wide, so an id means the same National Insurance category for every agency.\n\nAn id that does not match a National Insurance category returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "PaymentFrequencies", "item": [ { "name": "List payment frequencies", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/payment-frequencies", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "payment-frequencies" ], "variable": [] }, "description": "Returns every payment frequency the platform publishes. How often a worker prefers to be paid. The values are `Weekly`, `Fortnightly`, `Four Weekly` and `Monthly`.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a payment frequency id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get payment frequency details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/payment-frequencies/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "payment-frequencies", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one payment frequency by id. How often a worker prefers to be paid. The values are `Weekly`, `Fortnightly`, `Four Weekly` and `Monthly`.\n\nPayment frequencies are platform-wide, so an id means the same payment frequency for every agency.\n\nAn id that does not match a payment frequency returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "PaymentMethods", "item": [ { "name": "List payment methods", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/payment-methods", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "payment-methods" ], "variable": [] }, "description": "Returns every payment method the platform publishes. How a worker prefers to be paid. The values are `BACS`, `Direct BACS`, `Cheque` and `Salary Payments`.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a payment method — `paymentMethodId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get payment method details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/payment-methods/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "payment-methods", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one payment method by id. How a worker prefers to be paid. The values are `BACS`, `Direct BACS`, `Cheque` and `Salary Payments`.\n\nPayment methods are platform-wide, so an id means the same payment method for every agency.\n\nAn id that does not match a payment method returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "PrimaryRateTypes", "item": [ { "name": "List primary rate types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/primary-rate-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "primary-rate-types" ], "variable": [] }, "description": "Returns every primary rate type the platform publishes. The bands a client's rates are set up under, which decide what a worker's hours are paid at. Weekday, Saturday, Sunday and bank holiday each have a basic and an overtime band, alongside `Nightout`, `Pre Tax Expense`, `Post Tax Expense` and `Deduction`.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a primary rate type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get primary rate type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/primary-rate-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "primary-rate-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one primary rate type by id. The bands a client's rates are set up under, which decide what a worker's hours are paid at. Weekday, Saturday, Sunday and bank holiday each have a basic and an overtime band, alongside `Nightout`, `Pre Tax Expense`, `Post Tax Expense` and `Deduction`.\n\nPrimary rate types are platform-wide, so an id means the same primary rate type for every agency.\n\nAn id that does not match a primary rate type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "RateContractTypes", "item": [ { "name": "List rate contract types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/rate-contract-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "rate-contract-types" ], "variable": [] }, "description": "Returns every rate contract type the platform publishes. Every rate contract is created with the same type, so nothing on this API asks you to choose one.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a rate contract type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get rate contract type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/rate-contract-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "rate-contract-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one rate contract type by id. Every rate contract is created with the same type, so nothing on this API asks you to choose one.\n\nRate contract types are platform-wide, so an id means the same rate contract type for every agency.\n\nAn id that does not match a rate contract type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "SubContractorStatusTypes", "item": [ { "name": "List subcontractor status types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/sub-contractor-status-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "sub-contractor-status-types" ], "variable": [] }, "description": "Returns every subcontractor status type the platform publishes. The statuses a subcontractor can be held under. `Archived` is the only one defined today.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a subcontractor status type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get subcontractor status type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/sub-contractor-status-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "sub-contractor-status-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one subcontractor status type by id. The statuses a subcontractor can be held under. `Archived` is the only one defined today.\n\nSubcontractor status types are platform-wide, so an id means the same subcontractor status type for every agency.\n\nAn id that does not match a subcontractor status type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "Titles", "item": [ { "name": "List titles", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/titles", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "titles" ], "variable": [] }, "description": "Returns every title the platform publishes. A person's title — Mr, Miss, Mrs and the rest. The same vocabulary serves workers, contact persons and users.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a title — `titleId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get title details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/titles/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "titles", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one title by id. A person's title — Mr, Miss, Mrs and the rest. The same vocabulary serves workers, contact persons and users.\n\nTitles are platform-wide, so an id means the same title for every agency.\n\nAn id that does not match a title returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "VehicleCategories", "item": [ { "name": "List vehicle categories", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/vehicle-categories", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "vehicle-categories" ], "variable": [] }, "description": "Returns every vehicle category the platform publishes. The DVLA licence categories a driver can hold.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a vehicle category id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get vehicle category details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/vehicle-categories/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "vehicle-categories", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one vehicle category by id. The DVLA licence categories a driver can hold.\n\nVehicle categories are platform-wide, so an id means the same vehicle category for every agency.\n\nAn id that does not match a vehicle category returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "WorkerStatusTypes", "item": [ { "name": "List worker status types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/worker-status-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "worker-status-types" ], "variable": [] }, "description": "Returns every worker status type the platform publishes. The statuses a worker can be held under — `Active`, `Archived`, `Blacklisted`, `Not Suitable`, `Unauthorised`, `Pre-Registered`, `In Progress` and `Manual`. A worker can carry more than one.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. No endpoint published on this API takes a worker status type id yet; the vocabulary is published so that its values are enumerable.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get worker status type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/worker-status-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "worker-status-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one worker status type by id. The statuses a worker can be held under — `Active`, `Archived`, `Blacklisted`, `Not Suitable`, `Unauthorised`, `Pre-Registered`, `In Progress` and `Manual`. A worker can carry more than one.\n\nWorker status types are platform-wide, so an id means the same worker status type for every agency.\n\nAn id that does not match a worker status type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] }, { "name": "WorkerTypes", "item": [ { "name": "List worker types", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/worker-types", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "worker-types" ], "variable": [] }, "description": "Returns every worker type the platform publishes. The basis an agency engages a worker on. The values are `Temporary`, `Permanent`, `Commercial Permanent`, `Limited`, `PSC-In Scope`, `PSC-Out of Scope` and `Swedish Derogation`.\n\nThese values are platform-wide: every agency sees the same list and the same ids, and your agency cannot add to them or change them. Use the `id` wherever a request asks for a worker type — `workerTypeId` on CreateWorker.\n\nThe list is not paged, and no order is guaranteed — sort client-side if you need one. The values change very rarely, so cache them rather than fetching them before every call.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] }, { "name": "Get worker type details", "request": { "method": "GET", "header": [ { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/v1/reference/worker-types/:id", "host": [ "{{baseUrl}}" ], "path": [ "v1", "reference", "worker-types", ":id" ], "variable": [ { "key": "id", "value": "", "description": "Required." } ] }, "description": "Returns one worker type by id. The basis an agency engages a worker on. The values are `Temporary`, `Permanent`, `Commercial Permanent`, `Limited`, `PSC-In Scope`, `PSC-Out of Scope` and `Swedish Derogation`.\n\nWorker types are platform-wide, so an id means the same worker type for every agency.\n\nAn id that does not match a worker type returns 404.\n\n**Access.** Requires an authenticated token. No further policy is applied." }, "response": [] } ] } ] }, { "name": "Access", "description": "Obtaining and using credentials.", "item": [ { "name": "ApiAuth", "item": [ { "name": "Exchange client credentials for an access token", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "url": { "raw": "{{baseUrl}}/apiauth", "host": [ "{{baseUrl}}" ], "path": [ "apiauth" ], "variable": [] }, "body": { "mode": "raw", "raw": "{\n \"clientId\": \"{{clientId}}\",\n \"clientSecret\": \"{{clientSecret}}\",\n \"grantType\": \"client_credentials\"\n}" }, "description": "Exchanges the client id and secret issued to your API app for an access token. Every business operation in this API requires the resulting token in an `Authorization: Bearer {token}` header.\n\n**No sign-in is required.** The client id and secret go in the request body, not the header, and authenticate the call on their own. Both are issued from the Recruso Developer Console, not through this API.\n\n`grantType` must be `client_credentials`. The token is bound to the agency that owns the API app, which is what scopes every subsequent request — you never pass an agency id yourself. Writes are attributed to the Recruso user the app belongs to.\n\nAn unknown client id, a wrong secret, a revoked or expired credential, an inactive app, a caller outside the app's configured IP allow-list, or an app whose owning user has been disabled all return 401 without distinguishing between them.\n\nThis endpoint is rate limited. Read `expiresIn` and request a new token only once the current one elapses — exchanging credentials before every call returns 429.\n\n**Access.** This endpoint does not require authentication.", "auth": { "type": "noauth" } }, "response": [], "event": [ { "listen": "test", "script": { "type": "text/javascript", "exec": [ "const body = pm.response.json();", "if (body.accessToken) pm.collectionVariables.set(\"accessToken\", body.accessToken);" ] } } ] } ] } ] } ] }