API reference

Recruitment

41 requests. Each shows the permission a key needs, what to send and what comes back.

On this page

Applicants (the board or a list), with counts by stage, and the jobs address

GET/v1/recruitment/applicants

Permission: recruit.view
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`view`	query	enum	One of `list`, `board` · Default `"list"`
`stage`	query	enum	One of `new`, `screening`, `interview`, `onboarding`, `on_trial`, `hired`, `rejected`, `withdrawn`, `open`, `all` · Default `"open"`
`roleId`	query	uuid
`source`	query	enum	One of `careers`, `email`, `manual`
`q`	query	string
`quiet`	query	enum	One of `1`
`due`	query	enum	One of `1`

Response object

applicantsarray of objectrequired
- iduuidrequired
- namestringrequired
- emailstringrequiredcan be null
- phonestringrequiredcan be null
- areastringrequiredcan be null
- stageenumrequired
  One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
- sourceenumrequired
  One of "careers", "email", "manual"
- rolesarray of objectrequired
  - iduuidrequired
  - titlestringrequired
- assignedUserIduuidrequiredcan be null
- assignedNamestringrequiredcan be null
- nextActionOndaterequiredcan be null
  YYYY-MM-DD
- nextActionstringrequiredcan be null
- overduebooleanrequired
- goneQuietbooleanrequired
- unreadbooleanrequired
- filesintegerrequired
  -9007199254740991 to 9007199254740991
- daysInStageintegerrequired
  -9007199254740991 to 9007199254740991
- lastActivityAtstringrequired
- lastActivitystringrequiredcan be null
- createdAtstringrequired
countsobjectrequired
quietintegerrequired
-9007199254740991 to 9007199254740991
dueintegerrequired
-9007199254740991 to 9007199254740991
goneQuietDaysintegerrequired
-9007199254740991 to 9007199254740991
jobsAddressstringrequired
careersUrlstringrequiredcan be null

curl "https://app.workscope.co.uk/v1/recruitment/applicants" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "applicants": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "name": "Harbourside Dental",
      "email": "office@example.co.uk",
      "phone": "0117 496 0123",
      "area": "text",
      "stage": "new",
      "source": "careers",
      "roles": [
        {
          "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
          "title": "text"
        }
      ],
      "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "assignedName": "Harbourside Dental",
      "nextActionOn": "2026-11-06",
      "nextAction": "text",
      "overdue": false,
      "goneQuiet": false,
      "unread": false,
      "files": -9007199254740991,
      "daysInStage": -9007199254740991,
      "lastActivityAt": "2026-11-06T09:30:00.000Z",
      "lastActivity": "text",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "counts": {},
  "quiet": -9007199254740991,
  "due": -9007199254740991,
  "goneQuietDays": -9007199254740991,
  "jobsAddress": "1 Harbour Road, Bristol",
  "careersUrl": "https://example.co.uk"
}

Add an applicant by hand. An email address already an applicant adds to them (linked: true).

POST/v1/recruitment/applicants

Permission: recruit.manage
Module: recruitment
Answers: 201

Request body JSON

namestringrequired
1–200 characters
emailconstant or stringoptionalcan be null
phonestringoptionalcan be null
Up to 50 characters
areastringoptionalcan be null
Up to 120 characters
availabilitystringoptionalcan be null
Up to 500 characters
rightToWorkbooleanoptionalcan be null
messagestringoptionalcan be null
Up to 20000 characters
assignedUserIduuidoptionalcan be null
nextActionOndateoptionalcan be null
YYYY-MM-DD
nextActionstringoptionalcan be null
Up to 300 characters
roleIduuidoptionalcan be null

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null
linkedbooleanrequired

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "email": "",
    "phone": "0117 496 0123",
    "area": "text",
    "availability": "text",
    "rightToWork": false,
    "message": "text",
    "assignedUserId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "nextActionOn": "2026-11-06",
    "nextAction": "text",
    "roleId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text",
  "linked": false
}

One applicant and their timeline (marks them read)

GET/v1/recruitment/applicants/{id}

Permission: recruit.view
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl "https://app.workscope.co.uk/v1/recruitment/applicants/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Change an applicant: details, stage, roles, who has them, next action

PATCH/v1/recruitment/applicants/{id}

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

namestringoptional
1–200 characters
emailconstant or stringoptionalcan be null
phonestringoptionalcan be null
Up to 50 characters
areastringoptionalcan be null
Up to 120 characters
availabilitystringoptionalcan be null
Up to 500 characters
rightToWorkbooleanoptionalcan be null
messagestringoptionalcan be null
Up to 20000 characters
assignedUserIduuidoptionalcan be null
nextActionOndateoptionalcan be null
YYYY-MM-DD
nextActionstringoptionalcan be null
Up to 300 characters
stageenumoptional
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
roleIdsarray of uuidoptional
Up to 20 items

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X PATCH "https://app.workscope.co.uk/v1/recruitment/applicants/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "email": "",
    "phone": "0117 496 0123",
    "area": "text",
    "availability": "text",
    "rightToWork": false,
    "message": "text",
    "assignedUserId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "nextActionOn": "2026-11-06",
    "nextAction": "text",
    "stage": "new",
    "roleIds": [
      "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f"
    ]
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Delete an applicant for good: their timeline, emails, files and onboarding (recorded, without their name, in the privacy log)

DELETE/v1/recruitment/applicants/{id}

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

curl -X DELETE "https://app.workscope.co.uk/v1/recruitment/applicants/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "ok": true
}

Email the applicant. Their answer comes back to them here. Links may only be to Workscope.

POST/v1/recruitment/applicants/{id}/email

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

subjectstringrequired
1–300 characters
bodystringrequired
1–20000 characters

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/email" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "text",
    "body": "Side gate code is on the key safe."
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

A ready-written email (thanks for applying, asking for more, or not this time) in the company's own words

GET/v1/recruitment/applicants/{id}/email-draft

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired
`kind`	query	enumrequired	One of `applicant_received`, `applicant_info`, `applicant_reject`

Response object

tostringrequiredcan be null
subjectstringrequired
messagestringrequired

curl "https://app.workscope.co.uk/v1/recruitment/applicants/ID/email-draft?kind=applicant_received" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "to": "2026-11-06",
  "subject": "text",
  "message": "text"
}

A file that came with an application or an email

GET/v1/recruitment/applicants/{id}/events/{eventId}/attachments/{index}

Permission: recruit.view
Module: recruitment
Answers: 200 with a file (image/jpeg)

Parameters

Name	In	Kind
`id`	path	uuidrequired
`eventId`	path	uuidrequired
`index`	path	integerrequired

curl "https://app.workscope.co.uk/v1/recruitment/applicants/ID/events/ID/attachments/INDEX" \
  -H "Authorization: Bearer wsk_your_key_here"

Download everything held about an applicant: a ZIP of their record, timeline and files (recorded in the privacy log)

GET/v1/recruitment/applicants/{id}/export

Permission: recruit.manage
Module: recruitment
Answers: 200 with a file (image/jpeg)

Parameters

Name	In	Kind
`id`	path	uuidrequired

curl "https://app.workscope.co.uk/v1/recruitment/applicants/ID/export" \
  -H "Authorization: Bearer wsk_your_key_here"

Add a file (a CV, a certificate): send the file itself as application/octet-stream, its name in the query

POST/v1/recruitment/applicants/{id}/files

Permission: recruit.manage
Module: recruitment
Answers: 201

Parameters

Name	In	Kind
`id`	path	uuidrequired
`name`	query	stringrequired

Request body the file itself

Send the file as the body, with Content-Type one of application/octet-stream. See Files and photos.

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/files?name=Harbourside%20Dental" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file.pdf

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Notes from an interview, with a score from 1 to 5 if given

POST/v1/recruitment/applicants/{id}/interview-notes

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

bodystringrequired
1–10000 characters
scoreintegeroptionalcan be null
1 to 5

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/interview-notes" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Side gate code is on the key safe.",
    "score": 1
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Book an interview: a booking on the interviewer's schedule (internal, never invoiced), and the invite emailed with a calendar file

POST/v1/recruitment/applicants/{id}/interviews

Permission: recruit.manage or booking.manage
Module: recruitment
Answers: 201

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

datedaterequired
YYYY-MM-DD
starttimerequired
HH:MM, 24-hour
endtimerequired
HH:MM, 24-hour
teamMemberIduuidrequired
placeenumoptional
One of "office", "other", "phone", "video" · Default "office"
placeTextstringoptionalcan be null
Up to 500 characters
emailbooleanoptional
Default true

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/interviews" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "date": "2026-11-06",
    "start": "09:00",
    "end": "11:00",
    "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "place": "office",
    "placeText": "text",
    "email": true
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Keep an applicant for another retention period instead of deleting them, saying why

POST/v1/recruitment/applicants/{id}/keep

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

reasonstringrequired
1–500 characters

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/keep" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "text"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Add a note or a call to the timeline

POST/v1/recruitment/applicants/{id}/notes

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

kindenumoptional
One of "note", "call" · Default "note"
bodystringrequired
1–10000 characters

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/notes" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "note",
    "body": "Side gate code is on the key safe."
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Their onboarding: the checklist, what they gave (NI and bank masked), files and the signed contract

GET/v1/recruitment/applicants/{id}/onboarding

Permission: recruit.view
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

statusenumrequired
One of "open", "submitted", "approved"
expiresAtstringrequired
expiredbooleanrequired
startDatedaterequiredcan be null
YYYY-MM-DD
roleTitlestringrequiredcan be null
linkstringrequired
stepsobjectrequired
submittedAtstringrequiredcan be null
approvedAtstringrequiredcan be null
paystringrequiredcan be null
hoursstringrequiredcan be null
contractTemplateNamestringrequiredcan be null
detailsobjectrequired
- namestringrequiredcan be null
- surnamestringrequiredcan be null
- phonestringrequiredcan be null
- addressstringrequiredcan be null
- dateOfBirthdaterequiredcan be null
  YYYY-MM-DD
niNumberMaskedstringrequiredcan be null
bankMaskedstringrequiredcan be null
emergencyobjectrequiredcan be null
- namestringrequired
- relationshipstringrequiredcan be null
- phonestringrequired
dbsNumberstringrequiredcan be null
filesarray of objectrequired
- indexintegerrequired
  -9007199254740991 to 9007199254740991
- kindenumrequired
  One of "right_to_work", "dbs"
- filenamestringrequired
- bytesintegerrequired
  -9007199254740991 to 9007199254740991
- urlstringrequired
rightToWorkCheckedAtstringrequiredcan be null
rightToWorkCheckedBystringrequiredcan be null
dbsCheckedAtstringrequiredcan be null
dbsCheckedBystringrequiredcan be null
contractobjectrequired
- textstringrequiredcan be null
- signedNamestringrequiredcan be null
- signedAtstringrequiredcan be null
- signedIpstringrequiredcan be null
- hashstringrequiredcan be null
- signatureUrlstringrequiredcan be null
teamMemberIduuidrequiredcan be null

curl "https://app.workscope.co.uk/v1/recruitment/applicants/ID/onboarding" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "status": "open",
  "expiresAt": "2026-11-06T09:30:00.000Z",
  "expired": false,
  "startDate": "2026-11-06",
  "roleTitle": "text",
  "link": "text",
  "steps": {},
  "submittedAt": "2026-11-06T09:30:00.000Z",
  "approvedAt": "2026-11-06T09:30:00.000Z",
  "pay": "text",
  "hours": "text",
  "contractTemplateName": "Harbourside Dental",
  "details": {
    "name": "Harbourside Dental",
    "surname": "Harbourside Dental",
    "phone": "0117 496 0123",
    "address": "1 Harbour Road, Bristol",
    "dateOfBirth": "2026-11-06"
  },
  "niNumberMasked": "text",
  "bankMasked": "text",
  "emergency": {
    "name": "Harbourside Dental",
    "relationship": "text",
    "phone": "0117 496 0123"
  },
  "dbsNumber": "text",
  "files": [
    {
      "index": -9007199254740991,
      "kind": "right_to_work",
      "filename": "Harbourside Dental",
      "bytes": -9007199254740991,
      "url": "https://example.co.uk"
    }
  ],
  "rightToWorkCheckedAt": "2026-11-06T09:30:00.000Z",
  "rightToWorkCheckedBy": "text",
  "dbsCheckedAt": "2026-11-06T09:30:00.000Z",
  "dbsCheckedBy": "text",
  "contract": {
    "text": "text",
    "signedName": "Harbourside Dental",
    "signedAt": "2026-11-06T09:30:00.000Z",
    "signedIp": "text",
    "hash": "text",
    "signatureUrl": "https://example.co.uk"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41"
}

Start onboarding: a private link for 14 days where they give their details and sign their contract (emailed unless email is false)

POST/v1/recruitment/applicants/{id}/onboarding

Permission: recruit.manage
Module: recruitment
Answers: 201

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

startDatedaterequired
YYYY-MM-DD
roleTitlestringoptionalcan be null
Up to 120 characters
paystringoptionalcan be null
Up to 120 characters
hoursstringoptionalcan be null
Up to 120 characters
contractTemplateIduuidoptionalcan be null
emailbooleanoptional
Default true

Response object

statusenumrequired
One of "open", "submitted", "approved"
expiresAtstringrequired
expiredbooleanrequired
startDatedaterequiredcan be null
YYYY-MM-DD
roleTitlestringrequiredcan be null
linkstringrequired
stepsobjectrequired
submittedAtstringrequiredcan be null
approvedAtstringrequiredcan be null
paystringrequiredcan be null
hoursstringrequiredcan be null
contractTemplateNamestringrequiredcan be null
detailsobjectrequired
- namestringrequiredcan be null
- surnamestringrequiredcan be null
- phonestringrequiredcan be null
- addressstringrequiredcan be null
- dateOfBirthdaterequiredcan be null
  YYYY-MM-DD
niNumberMaskedstringrequiredcan be null
bankMaskedstringrequiredcan be null
emergencyobjectrequiredcan be null
- namestringrequired
- relationshipstringrequiredcan be null
- phonestringrequired
dbsNumberstringrequiredcan be null
filesarray of objectrequired
- indexintegerrequired
  -9007199254740991 to 9007199254740991
- kindenumrequired
  One of "right_to_work", "dbs"
- filenamestringrequired
- bytesintegerrequired
  -9007199254740991 to 9007199254740991
- urlstringrequired
rightToWorkCheckedAtstringrequiredcan be null
rightToWorkCheckedBystringrequiredcan be null
dbsCheckedAtstringrequiredcan be null
dbsCheckedBystringrequiredcan be null
contractobjectrequired
- textstringrequiredcan be null
- signedNamestringrequiredcan be null
- signedAtstringrequiredcan be null
- signedIpstringrequiredcan be null
- hashstringrequiredcan be null
- signatureUrlstringrequiredcan be null
teamMemberIduuidrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/onboarding" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "pay": "text",
    "hours": "text",
    "contractTemplateId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "email": true
  }'

Example response

{
  "status": "open",
  "expiresAt": "2026-11-06T09:30:00.000Z",
  "expired": false,
  "startDate": "2026-11-06",
  "roleTitle": "text",
  "link": "text",
  "steps": {},
  "submittedAt": "2026-11-06T09:30:00.000Z",
  "approvedAt": "2026-11-06T09:30:00.000Z",
  "pay": "text",
  "hours": "text",
  "contractTemplateName": "Harbourside Dental",
  "details": {
    "name": "Harbourside Dental",
    "surname": "Harbourside Dental",
    "phone": "0117 496 0123",
    "address": "1 Harbour Road, Bristol",
    "dateOfBirth": "2026-11-06"
  },
  "niNumberMasked": "text",
  "bankMasked": "text",
  "emergency": {
    "name": "Harbourside Dental",
    "relationship": "text",
    "phone": "0117 496 0123"
  },
  "dbsNumber": "text",
  "files": [
    {
      "index": -9007199254740991,
      "kind": "right_to_work",
      "filename": "Harbourside Dental",
      "bytes": -9007199254740991,
      "url": "https://example.co.uk"
    }
  ],
  "rightToWorkCheckedAt": "2026-11-06T09:30:00.000Z",
  "rightToWorkCheckedBy": "text",
  "dbsCheckedAt": "2026-11-06T09:30:00.000Z",
  "dbsCheckedBy": "text",
  "contract": {
    "text": "text",
    "signedName": "Harbourside Dental",
    "signedAt": "2026-11-06T09:30:00.000Z",
    "signedIp": "text",
    "hash": "text",
    "signatureUrl": "https://example.co.uk"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41"
}

Make them a team member On trial from what they gave (nothing typed again), with their documents, an app invite and a welcome email

POST/v1/recruitment/applicants/{id}/onboarding/approve

Permission: recruit.manage or team.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

invitebooleanoptional
Default true

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/onboarding/approve" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invite": true
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

Tick (or untick) that their right to work and DBS were checked

POST/v1/recruitment/applicants/{id}/onboarding/checks

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

rightToWorkbooleanoptional
dbsbooleanoptional

Response object

statusenumrequired
One of "open", "submitted", "approved"
expiresAtstringrequired
expiredbooleanrequired
startDatedaterequiredcan be null
YYYY-MM-DD
roleTitlestringrequiredcan be null
linkstringrequired
stepsobjectrequired
submittedAtstringrequiredcan be null
approvedAtstringrequiredcan be null
paystringrequiredcan be null
hoursstringrequiredcan be null
contractTemplateNamestringrequiredcan be null
detailsobjectrequired
- namestringrequiredcan be null
- surnamestringrequiredcan be null
- phonestringrequiredcan be null
- addressstringrequiredcan be null
- dateOfBirthdaterequiredcan be null
  YYYY-MM-DD
niNumberMaskedstringrequiredcan be null
bankMaskedstringrequiredcan be null
emergencyobjectrequiredcan be null
- namestringrequired
- relationshipstringrequiredcan be null
- phonestringrequired
dbsNumberstringrequiredcan be null
filesarray of objectrequired
- indexintegerrequired
  -9007199254740991 to 9007199254740991
- kindenumrequired
  One of "right_to_work", "dbs"
- filenamestringrequired
- bytesintegerrequired
  -9007199254740991 to 9007199254740991
- urlstringrequired
rightToWorkCheckedAtstringrequiredcan be null
rightToWorkCheckedBystringrequiredcan be null
dbsCheckedAtstringrequiredcan be null
dbsCheckedBystringrequiredcan be null
contractobjectrequired
- textstringrequiredcan be null
- signedNamestringrequiredcan be null
- signedAtstringrequiredcan be null
- signedIpstringrequiredcan be null
- hashstringrequiredcan be null
- signatureUrlstringrequiredcan be null
teamMemberIduuidrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/onboarding/checks" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "rightToWork": false,
    "dbs": false
  }'

Example response

{
  "status": "open",
  "expiresAt": "2026-11-06T09:30:00.000Z",
  "expired": false,
  "startDate": "2026-11-06",
  "roleTitle": "text",
  "link": "text",
  "steps": {},
  "submittedAt": "2026-11-06T09:30:00.000Z",
  "approvedAt": "2026-11-06T09:30:00.000Z",
  "pay": "text",
  "hours": "text",
  "contractTemplateName": "Harbourside Dental",
  "details": {
    "name": "Harbourside Dental",
    "surname": "Harbourside Dental",
    "phone": "0117 496 0123",
    "address": "1 Harbour Road, Bristol",
    "dateOfBirth": "2026-11-06"
  },
  "niNumberMasked": "text",
  "bankMasked": "text",
  "emergency": {
    "name": "Harbourside Dental",
    "relationship": "text",
    "phone": "0117 496 0123"
  },
  "dbsNumber": "text",
  "files": [
    {
      "index": -9007199254740991,
      "kind": "right_to_work",
      "filename": "Harbourside Dental",
      "bytes": -9007199254740991,
      "url": "https://example.co.uk"
    }
  ],
  "rightToWorkCheckedAt": "2026-11-06T09:30:00.000Z",
  "rightToWorkCheckedBy": "text",
  "dbsCheckedAt": "2026-11-06T09:30:00.000Z",
  "dbsCheckedBy": "text",
  "contract": {
    "text": "text",
    "signedName": "Harbourside Dental",
    "signedAt": "2026-11-06T09:30:00.000Z",
    "signedIp": "text",
    "hash": "text",
    "signatureUrl": "https://example.co.uk"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41"
}

A document they uploaded (right to work, DBS)

GET/v1/recruitment/applicants/{id}/onboarding/files/{index}

Permission: recruit.view
Module: recruitment
Answers: 200 with a file (image/jpeg)

Parameters

Name	In	Kind
`id`	path	uuidrequired
`index`	path	integerrequired

curl "https://app.workscope.co.uk/v1/recruitment/applicants/ID/onboarding/files/INDEX" \
  -H "Authorization: Bearer wsk_your_key_here"

Another 14 days on the onboarding link, and the email again

POST/v1/recruitment/applicants/{id}/onboarding/resend

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

statusenumrequired
One of "open", "submitted", "approved"
expiresAtstringrequired
expiredbooleanrequired
startDatedaterequiredcan be null
YYYY-MM-DD
roleTitlestringrequiredcan be null
linkstringrequired
stepsobjectrequired
submittedAtstringrequiredcan be null
approvedAtstringrequiredcan be null
paystringrequiredcan be null
hoursstringrequiredcan be null
contractTemplateNamestringrequiredcan be null
detailsobjectrequired
- namestringrequiredcan be null
- surnamestringrequiredcan be null
- phonestringrequiredcan be null
- addressstringrequiredcan be null
- dateOfBirthdaterequiredcan be null
  YYYY-MM-DD
niNumberMaskedstringrequiredcan be null
bankMaskedstringrequiredcan be null
emergencyobjectrequiredcan be null
- namestringrequired
- relationshipstringrequiredcan be null
- phonestringrequired
dbsNumberstringrequiredcan be null
filesarray of objectrequired
- indexintegerrequired
  -9007199254740991 to 9007199254740991
- kindenumrequired
  One of "right_to_work", "dbs"
- filenamestringrequired
- bytesintegerrequired
  -9007199254740991 to 9007199254740991
- urlstringrequired
rightToWorkCheckedAtstringrequiredcan be null
rightToWorkCheckedBystringrequiredcan be null
dbsCheckedAtstringrequiredcan be null
dbsCheckedBystringrequiredcan be null
contractobjectrequired
- textstringrequiredcan be null
- signedNamestringrequiredcan be null
- signedAtstringrequiredcan be null
- signedIpstringrequiredcan be null
- hashstringrequiredcan be null
- signatureUrlstringrequiredcan be null
teamMemberIduuidrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/onboarding/resend" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "status": "open",
  "expiresAt": "2026-11-06T09:30:00.000Z",
  "expired": false,
  "startDate": "2026-11-06",
  "roleTitle": "text",
  "link": "text",
  "steps": {},
  "submittedAt": "2026-11-06T09:30:00.000Z",
  "approvedAt": "2026-11-06T09:30:00.000Z",
  "pay": "text",
  "hours": "text",
  "contractTemplateName": "Harbourside Dental",
  "details": {
    "name": "Harbourside Dental",
    "surname": "Harbourside Dental",
    "phone": "0117 496 0123",
    "address": "1 Harbour Road, Bristol",
    "dateOfBirth": "2026-11-06"
  },
  "niNumberMasked": "text",
  "bankMasked": "text",
  "emergency": {
    "name": "Harbourside Dental",
    "relationship": "text",
    "phone": "0117 496 0123"
  },
  "dbsNumber": "text",
  "files": [
    {
      "index": -9007199254740991,
      "kind": "right_to_work",
      "filename": "Harbourside Dental",
      "bytes": -9007199254740991,
      "url": "https://example.co.uk"
    }
  ],
  "rightToWorkCheckedAt": "2026-11-06T09:30:00.000Z",
  "rightToWorkCheckedBy": "text",
  "dbsCheckedAt": "2026-11-06T09:30:00.000Z",
  "dbsCheckedBy": "text",
  "contract": {
    "text": "text",
    "signedName": "Harbourside Dental",
    "signedAt": "2026-11-06T09:30:00.000Z",
    "signedIp": "text",
    "hash": "text",
    "signatureUrl": "https://example.co.uk"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41"
}

The signature their contract was signed with

GET/v1/recruitment/applicants/{id}/onboarding/signature

Permission: recruit.view
Module: recruitment
Answers: 200 with a file (image/jpeg)

Parameters

Name	In	Kind
`id`	path	uuidrequired

curl "https://app.workscope.co.uk/v1/recruitment/applicants/ID/onboarding/signature" \
  -H "Authorization: Bearer wsk_your_key_here"

Mark an applicant read (or unread again)

POST/v1/recruitment/applicants/{id}/read

Permission: recruit.view
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

unreadbooleanoptional
Default false

Response object

okconstantrequired
Always true

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/read" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "unread": false
  }'

Example response

{
  "ok": true
}

Move to Rejected, and (unless email is false) send the "not this time" email

POST/v1/recruitment/applicants/{id}/reject

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

emailbooleanoptional
Default true
subjectstringoptional
Up to 300 characters
bodystringoptional
Up to 20000 characters

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/reject" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": true,
    "subject": "text",
    "body": "Side gate code is on the key safe."
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

The end of the trial: keep them on (Hired), or it didn't work out (employment ends, future bookings go to nobody, the login stops)

POST/v1/recruitment/applicants/{id}/trial

Permission: recruit.manage or team.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

outcomeenumrequired
One of "keep", "end"
endDatedateoptionalcan be null
YYYY-MM-DD
reasonstringoptionalcan be null
Up to 1000 characters

Response object

iduuidrequired
namestringrequired
emailstringrequiredcan be null
phonestringrequiredcan be null
areastringrequiredcan be null
stageenumrequired
One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
sourceenumrequired
One of "careers", "email", "manual"
rolesarray of objectrequired
- iduuidrequired
- titlestringrequired
assignedUserIduuidrequiredcan be null
assignedNamestringrequiredcan be null
nextActionOndaterequiredcan be null
YYYY-MM-DD
nextActionstringrequiredcan be null
overduebooleanrequired
goneQuietbooleanrequired
unreadbooleanrequired
filesintegerrequired
-9007199254740991 to 9007199254740991
daysInStageintegerrequired
-9007199254740991 to 9007199254740991
lastActivityAtstringrequired
lastActivitystringrequiredcan be null
createdAtstringrequired
availabilitystringrequiredcan be null
rightToWorkbooleanrequiredcan be null
messagestringrequiredcan be null
jobsAddressstringrequired
eventsarray of objectrequired
- iduuidrequired
- kindenumrequired
  One of "created", "applied", "email_in", "email_out", "note", "call", "stage", "file", "assigned", "interview", "onboarding", "trial", "retention"
- subjectstringrequiredcan be null
- bodystringrequiredcan be null
- fromAddressstringrequiredcan be null
- toAddressstringrequiredcan be null
- attachmentsarray of objectrequired
  - indexintegerrequired
    -9007199254740991 to 9007199254740991
  - filenamestringrequired
  - contentTypestringrequired
  - bytesintegerrequired
    -9007199254740991 to 9007199254740991
  - urlstringrequired
- metaobjectrequired
- deliveryobjectrequiredcan be null
  - statusenumrequired
    One of "queued", "sent", "not_sent", "delivered", "bounced", "complained", "failed"
  - detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired
interviewsarray of objectrequired
- bookingIduuidrequired
- datedaterequiredcan be null
  YYYY-MM-DD
- startstringrequiredcan be null
- endstringrequiredcan be null
- teamMemberIduuidrequiredcan be null
- interviewerNamestringrequiredcan be null
- placeenumrequired
  One of "office", "other", "phone", "video"
- placeTextstringrequiredcan be null
- wherestringrequired
- statusstringrequired
- pastbooleanrequired
interviewScoreintegerrequiredcan be null
-9007199254740991 to 9007199254740991
onboardingobjectrequiredcan be null
- statusenumrequired
  One of "open", "submitted", "approved"
- expiresAtstringrequired
- expiredbooleanrequired
- startDatedaterequiredcan be null
  YYYY-MM-DD
- roleTitlestringrequiredcan be null
- linkstringrequired
- stepsobjectrequired
- submittedAtstringrequiredcan be null
- approvedAtstringrequiredcan be null
teamMemberIduuidrequiredcan be null
onTrialbooleanrequired
deleteOndaterequiredcan be null
YYYY-MM-DD
keptUntildaterequiredcan be null
YYYY-MM-DD
keptReasonstringrequiredcan be null

curl -X POST "https://app.workscope.co.uk/v1/recruitment/applicants/ID/trial" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "outcome": "keep",
    "endDate": "2026-11-06",
    "reason": "text"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "email": "office@example.co.uk",
  "phone": "0117 496 0123",
  "area": "text",
  "stage": "new",
  "source": "careers",
  "roles": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "title": "text"
    }
  ],
  "assignedUserId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
  "assignedName": "Harbourside Dental",
  "nextActionOn": "2026-11-06",
  "nextAction": "text",
  "overdue": false,
  "goneQuiet": false,
  "unread": false,
  "files": -9007199254740991,
  "daysInStage": -9007199254740991,
  "lastActivityAt": "2026-11-06T09:30:00.000Z",
  "lastActivity": "text",
  "createdAt": "2026-11-06T09:30:00.000Z",
  "availability": "text",
  "rightToWork": false,
  "message": "text",
  "jobsAddress": "1 Harbour Road, Bristol",
  "events": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "kind": "created",
      "subject": "text",
      "body": "Side gate code is on the key safe.",
      "fromAddress": "1 Harbour Road, Bristol",
      "toAddress": "1 Harbour Road, Bristol",
      "attachments": [
        {
          "index": -9007199254740991,
          "filename": "Harbourside Dental",
          "contentType": "text",
          "bytes": -9007199254740991,
          "url": "https://example.co.uk"
        }
      ],
      "meta": {},
      "delivery": {
        "status": "queued",
        "detail": "text"
      },
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ],
  "interviews": [
    {
      "bookingId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "date": "2026-11-06",
      "start": "09:00",
      "end": "11:00",
      "teamMemberId": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "interviewerName": "Harbourside Dental",
      "place": "office",
      "placeText": "text",
      "where": "text",
      "status": "text",
      "past": false
    }
  ],
  "interviewScore": -9007199254740991,
  "onboarding": {
    "status": "open",
    "expiresAt": "2026-11-06T09:30:00.000Z",
    "expired": false,
    "startDate": "2026-11-06",
    "roleTitle": "text",
    "link": "text",
    "steps": {},
    "submittedAt": "2026-11-06T09:30:00.000Z",
    "approvedAt": "2026-11-06T09:30:00.000Z"
  },
  "teamMemberId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "onTrial": false,
  "deleteOn": "2026-11-06",
  "keptUntil": "2026-11-06",
  "keptReason": "text"
}

The careers page settings (made, switched off, the first time)

GET/v1/recruitment/careers

Permission: recruit.view
Module: recruitment
Answers: 200

Response object

enabledbooleanrequired
slugstringrequired
urlstringrequired
colourstringrequired
headlinestringrequiredcan be null
aboutstringrequiredcan be null
perksarray of stringrequired
coverUrlstringrequiredcan be null
photosarray of objectrequired
- idstringrequired
- urlstringrequired
- thumbUrlstringrequired
speculativebooleanrequired
autoReplybooleanrequired
privacystringrequiredcan be null
logoUrlstringrequiredcan be null
companyNamestringrequired
retentionMonthsconstantrequired
Option 1: constant
Always 3
Option 2: constant
Always 6
Option 3: constant
Always 12
Option 4: constant
Always 24

curl "https://app.workscope.co.uk/v1/recruitment/careers" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "enabled": false,
  "slug": "example-slug",
  "url": "https://example.co.uk",
  "colour": "text",
  "headline": "text",
  "about": "text",
  "perks": [
    "text"
  ],
  "coverUrl": "https://example.co.uk",
  "photos": [
    {
      "id": "text",
      "url": "https://example.co.uk",
      "thumbUrl": "https://example.co.uk"
    }
  ],
  "speculative": false,
  "autoReply": false,
  "privacy": "text",
  "logoUrl": "https://example.co.uk",
  "companyName": "Harbourside Dental",
  "retentionMonths": 3
}

Change the careers page: switch it on, its address, colour, words, perks

PATCH/v1/recruitment/careers

Permission: recruit.manage
Module: recruitment
Answers: 200

Request body JSON

enabledbooleanoptional
slugstringoptional
Matches ^[a-z0-9]+(?:-[a-z0-9]+)*$ · 2–60 characters
colourstringoptional
Matches ^#[0-9a-fA-F]{6}$
headlinestringoptionalcan be null
Up to 160 characters
aboutstringoptionalcan be null
Up to 10000 characters
perksarray of stringoptional
Up to 12 items
speculativebooleanoptional
autoReplybooleanoptional
privacystringoptionalcan be null
Up to 3000 characters
retentionMonthsconstantoptional
Option 1: constant
Always 3
Option 2: constant
Always 6
Option 3: constant
Always 12
Option 4: constant
Always 24

Response object

enabledbooleanrequired
slugstringrequired
urlstringrequired
colourstringrequired
headlinestringrequiredcan be null
aboutstringrequiredcan be null
perksarray of stringrequired
coverUrlstringrequiredcan be null
photosarray of objectrequired
- idstringrequired
- urlstringrequired
- thumbUrlstringrequired
speculativebooleanrequired
autoReplybooleanrequired
privacystringrequiredcan be null
logoUrlstringrequiredcan be null
companyNamestringrequired
retentionMonthsconstantrequired
Option 1: constant
Always 3
Option 2: constant
Always 6
Option 3: constant
Always 12
Option 4: constant
Always 24

curl -X PATCH "https://app.workscope.co.uk/v1/recruitment/careers" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false,
    "slug": "example-slug",
    "colour": "#2563eb",
    "headline": "text",
    "about": "text",
    "perks": [
      "text"
    ],
    "speculative": false,
    "autoReply": false,
    "privacy": "text",
    "retentionMonths": 3
  }'

Example response

{
  "enabled": false,
  "slug": "example-slug",
  "url": "https://example.co.uk",
  "colour": "text",
  "headline": "text",
  "about": "text",
  "perks": [
    "text"
  ],
  "coverUrl": "https://example.co.uk",
  "photos": [
    {
      "id": "text",
      "url": "https://example.co.uk",
      "thumbUrl": "https://example.co.uk"
    }
  ],
  "speculative": false,
  "autoReply": false,
  "privacy": "text",
  "logoUrl": "https://example.co.uk",
  "companyName": "Harbourside Dental",
  "retentionMonths": 3
}

Set the cover picture: send the image itself (JPEG, PNG or WebP)

POST/v1/recruitment/careers/cover

Permission: recruit.manage
Module: recruitment
Answers: 200

Request body the file itself

Send the file as the body, with Content-Type one of image/jpeg, image/png, image/webp, image/heic, image/heif. See Files and photos.

Response object

enabledbooleanrequired
slugstringrequired
urlstringrequired
colourstringrequired
headlinestringrequiredcan be null
aboutstringrequiredcan be null
perksarray of stringrequired
coverUrlstringrequiredcan be null
photosarray of objectrequired
- idstringrequired
- urlstringrequired
- thumbUrlstringrequired
speculativebooleanrequired
autoReplybooleanrequired
privacystringrequiredcan be null
logoUrlstringrequiredcan be null
companyNamestringrequired
retentionMonthsconstantrequired
Option 1: constant
Always 3
Option 2: constant
Always 6
Option 3: constant
Always 12
Option 4: constant
Always 24

curl -X POST "https://app.workscope.co.uk/v1/recruitment/careers/cover" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

Example response

{
  "enabled": false,
  "slug": "example-slug",
  "url": "https://example.co.uk",
  "colour": "text",
  "headline": "text",
  "about": "text",
  "perks": [
    "text"
  ],
  "coverUrl": "https://example.co.uk",
  "photos": [
    {
      "id": "text",
      "url": "https://example.co.uk",
      "thumbUrl": "https://example.co.uk"
    }
  ],
  "speculative": false,
  "autoReply": false,
  "privacy": "text",
  "logoUrl": "https://example.co.uk",
  "companyName": "Harbourside Dental",
  "retentionMonths": 3
}

Take the cover picture off

DELETE/v1/recruitment/careers/cover

Permission: recruit.manage
Module: recruitment
Answers: 200

Response object

enabledbooleanrequired
slugstringrequired
urlstringrequired
colourstringrequired
headlinestringrequiredcan be null
aboutstringrequiredcan be null
perksarray of stringrequired
coverUrlstringrequiredcan be null
photosarray of objectrequired
- idstringrequired
- urlstringrequired
- thumbUrlstringrequired
speculativebooleanrequired
autoReplybooleanrequired
privacystringrequiredcan be null
logoUrlstringrequiredcan be null
companyNamestringrequired
retentionMonthsconstantrequired
Option 1: constant
Always 3
Option 2: constant
Always 6
Option 3: constant
Always 12
Option 4: constant
Always 24

curl -X DELETE "https://app.workscope.co.uk/v1/recruitment/careers/cover" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "enabled": false,
  "slug": "example-slug",
  "url": "https://example.co.uk",
  "colour": "text",
  "headline": "text",
  "about": "text",
  "perks": [
    "text"
  ],
  "coverUrl": "https://example.co.uk",
  "photos": [
    {
      "id": "text",
      "url": "https://example.co.uk",
      "thumbUrl": "https://example.co.uk"
    }
  ],
  "speculative": false,
  "autoReply": false,
  "privacy": "text",
  "logoUrl": "https://example.co.uk",
  "companyName": "Harbourside Dental",
  "retentionMonths": 3
}

An image on the careers page (logo, cover, a photo), for the preview

GET/v1/recruitment/careers/images/{id}

Permission: recruit.view
Module: recruitment
Answers: 200 with a file (image/jpeg)

Parameters

Name	In	Kind
`id`	path	stringrequired

curl "https://app.workscope.co.uk/v1/recruitment/careers/images/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Add a photo to "About us" (up to 8): send the image itself

POST/v1/recruitment/careers/photos

Permission: recruit.manage
Module: recruitment
Answers: 201

Request body the file itself

Send the file as the body, with Content-Type one of image/jpeg, image/png, image/webp, image/heic, image/heif. See Files and photos.

Response object

enabledbooleanrequired
slugstringrequired
urlstringrequired
colourstringrequired
headlinestringrequiredcan be null
aboutstringrequiredcan be null
perksarray of stringrequired
coverUrlstringrequiredcan be null
photosarray of objectrequired
- idstringrequired
- urlstringrequired
- thumbUrlstringrequired
speculativebooleanrequired
autoReplybooleanrequired
privacystringrequiredcan be null
logoUrlstringrequiredcan be null
companyNamestringrequired
retentionMonthsconstantrequired
Option 1: constant
Always 3
Option 2: constant
Always 6
Option 3: constant
Always 12
Option 4: constant
Always 24

curl -X POST "https://app.workscope.co.uk/v1/recruitment/careers/photos" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg

Example response

{
  "enabled": false,
  "slug": "example-slug",
  "url": "https://example.co.uk",
  "colour": "text",
  "headline": "text",
  "about": "text",
  "perks": [
    "text"
  ],
  "coverUrl": "https://example.co.uk",
  "photos": [
    {
      "id": "text",
      "url": "https://example.co.uk",
      "thumbUrl": "https://example.co.uk"
    }
  ],
  "speculative": false,
  "autoReply": false,
  "privacy": "text",
  "logoUrl": "https://example.co.uk",
  "companyName": "Harbourside Dental",
  "retentionMonths": 3
}

Take a photo off

DELETE/v1/recruitment/careers/photos/{id}

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	stringrequired

Response object

enabledbooleanrequired
slugstringrequired
urlstringrequired
colourstringrequired
headlinestringrequiredcan be null
aboutstringrequiredcan be null
perksarray of stringrequired
coverUrlstringrequiredcan be null
photosarray of objectrequired
- idstringrequired
- urlstringrequired
- thumbUrlstringrequired
speculativebooleanrequired
autoReplybooleanrequired
privacystringrequiredcan be null
logoUrlstringrequiredcan be null
companyNamestringrequired
retentionMonthsconstantrequired
Option 1: constant
Always 3
Option 2: constant
Always 6
Option 3: constant
Always 12
Option 4: constant
Always 24

curl -X DELETE "https://app.workscope.co.uk/v1/recruitment/careers/photos/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "enabled": false,
  "slug": "example-slug",
  "url": "https://example.co.uk",
  "colour": "text",
  "headline": "text",
  "about": "text",
  "perks": [
    "text"
  ],
  "coverUrl": "https://example.co.uk",
  "photos": [
    {
      "id": "text",
      "url": "https://example.co.uk",
      "thumbUrl": "https://example.co.uk"
    }
  ],
  "speculative": false,
  "autoReply": false,
  "privacy": "text",
  "logoUrl": "https://example.co.uk",
  "companyName": "Harbourside Dental",
  "retentionMonths": 3
}

The careers page as visitors would see it, even while switched off

GET/v1/recruitment/careers/preview

Permission: recruit.view
Module: recruitment
Answers: 200

Response object

slugstringrequired
companyNamestringrequired
websitestringrequiredcan be null
logoUrlstringrequiredcan be null
colourstringrequired
headlinestringrequiredcan be null
aboutstringrequiredcan be null
perksarray of stringrequired
coverUrlstringrequiredcan be null
photosarray of objectrequired
- idstringrequired
- urlstringrequired
- thumbUrlstringrequired
speculativebooleanrequired
privacystringrequired
rolesarray of objectrequired
- slugstringrequired
- titlestringrequired
- summarystringrequiredcan be null
- areastringrequiredcan be null
- hoursstringrequiredcan be null
- paystringrequiredcan be null
- employmentTypeenumrequired
  One of "employed", "self_employed"
- closesOndaterequiredcan be null
  YYYY-MM-DD
- descriptionstringrequiredcan be null
roleobjectrequiredcan be null
- slugstringrequired
- titlestringrequired
- summarystringrequiredcan be null
- areastringrequiredcan be null
- hoursstringrequiredcan be null
- paystringrequiredcan be null
- employmentTypeenumrequired
  One of "employed", "self_employed"
- closesOndaterequiredcan be null
  YYYY-MM-DD
- descriptionstringrequiredcan be null
previewbooleanrequired

curl "https://app.workscope.co.uk/v1/recruitment/careers/preview" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "slug": "example-slug",
  "companyName": "Harbourside Dental",
  "website": "https://example.co.uk",
  "logoUrl": "https://example.co.uk",
  "colour": "text",
  "headline": "text",
  "about": "text",
  "perks": [
    "text"
  ],
  "coverUrl": "https://example.co.uk",
  "photos": [
    {
      "id": "text",
      "url": "https://example.co.uk",
      "thumbUrl": "https://example.co.uk"
    }
  ],
  "speculative": false,
  "privacy": "text",
  "roles": [
    {
      "slug": "example-slug",
      "title": "text",
      "summary": "text",
      "area": "text",
      "hours": "text",
      "pay": "text",
      "employmentType": "employed",
      "closesOn": "2026-11-06",
      "description": "Side gate code is on the key safe."
    }
  ],
  "role": {
    "slug": "example-slug",
    "title": "text",
    "summary": "text",
    "area": "text",
    "hours": "text",
    "pay": "text",
    "employmentType": "employed",
    "closesOn": "2026-11-06",
    "description": "Side gate code is on the key safe."
  },
  "preview": false
}

Contract templates (the first one is made from Workscope's example the first time)

GET/v1/recruitment/contracts

Permission: recruit.view
Module: recruitment
Answers: 200

Response array of object

iduuidrequired
namestringrequired
bodystringrequired
archivedbooleanrequired
createdAtstringrequired

curl "https://app.workscope.co.uk/v1/recruitment/contracts" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "name": "Harbourside Dental",
    "body": "Side gate code is on the key safe.",
    "archived": false,
    "createdAt": "2026-11-06T09:30:00.000Z"
  }
]

Add a contract template

POST/v1/recruitment/contracts

Permission: recruit.manage
Module: recruitment
Answers: 201

Request body JSON

namestringrequired
1–120 characters
bodystringrequired
1–50000 characters
archivedbooleanoptional

Response object

iduuidrequired
namestringrequired
bodystringrequired
archivedbooleanrequired
createdAtstringrequired

curl -X POST "https://app.workscope.co.uk/v1/recruitment/contracts" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "body": "Side gate code is on the key safe.",
    "archived": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "body": "Side gate code is on the key safe.",
  "archived": false,
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Change or archive a contract template (contracts already sent keep their words)

PATCH/v1/recruitment/contracts/{id}

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

namestringoptional
1–120 characters
bodystringoptional
1–50000 characters
archivedbooleanoptional

Response object

iduuidrequired
namestringrequired
bodystringrequired
archivedbooleanrequired
createdAtstringrequired

curl -X PATCH "https://app.workscope.co.uk/v1/recruitment/contracts/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "body": "Side gate code is on the key safe.",
    "archived": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "body": "Side gate code is on the key safe.",
  "archived": false,
  "createdAt": "2026-11-06T09:30:00.000Z"
}

How many applicants have something nobody has opened yet (the Recruitment menu's number)

GET/v1/recruitment/counts

Permission: recruit.view
Module: recruitment
Answers: 200

Response object

unreadintegerrequired
-9007199254740991 to 9007199254740991

curl "https://app.workscope.co.uk/v1/recruitment/counts" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "unread": -9007199254740991
}

Applicants due for deletion in the next 30 days, and the privacy log

GET/v1/recruitment/retention

Permission: recruit.view
Module: recruitment
Answers: 200

Response object

monthsintegerrequired
-9007199254740991 to 9007199254740991
duearray of objectrequired
- iduuidrequired
- namestringrequired
- stageenumrequired
  One of "new", "screening", "interview", "onboarding", "on_trial", "hired", "rejected", "withdrawn"
- deleteOndaterequired
  YYYY-MM-DD
- keptUntildaterequiredcan be null
  YYYY-MM-DD
logarray of objectrequired
- iduuidrequired
- actionenumrequired
  One of "auto_deleted", "deleted", "exported", "kept"
- countintegerrequired
  -9007199254740991 to 9007199254740991
- detailstringrequiredcan be null
- userNamestringrequiredcan be null
- createdAtstringrequired

curl "https://app.workscope.co.uk/v1/recruitment/retention" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "months": -9007199254740991,
  "due": [
    {
      "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "name": "Harbourside Dental",
      "stage": "new",
      "deleteOn": "2026-11-06",
      "keptUntil": "2026-11-06"
    }
  ],
  "log": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "action": "auto_deleted",
      "count": 3,
      "detail": "text",
      "userName": "Harbourside Dental",
      "createdAt": "2026-11-06T09:30:00.000Z"
    }
  ]
}

The roles (open first), with how many applied for each

GET/v1/recruitment/roles

Permission: recruit.view
Module: recruitment
Answers: 200

Response array of object

iduuidrequired
titlestringrequired
slugstringrequired
summarystringrequiredcan be null
descriptionstringrequiredcan be null
areastringrequiredcan be null
hoursstringrequiredcan be null
paystringrequiredcan be null
employmentTypeenumrequired
One of "employed", "self_employed"
statusenumrequired
One of "draft", "open", "closed"
closesOndaterequiredcan be null
YYYY-MM-DD
applicantsintegerrequired
-9007199254740991 to 9007199254740991
openApplicantsintegerrequired
-9007199254740991 to 9007199254740991
createdAtstringrequired

curl "https://app.workscope.co.uk/v1/recruitment/roles" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "title": "text",
    "slug": "example-slug",
    "summary": "text",
    "description": "Side gate code is on the key safe.",
    "area": "text",
    "hours": "text",
    "pay": "text",
    "employmentType": "employed",
    "status": "draft",
    "closesOn": "2026-11-06",
    "applicants": -9007199254740991,
    "openApplicants": -9007199254740991,
    "createdAt": "2026-11-06T09:30:00.000Z"
  }
]

Add a role (a draft unless opened)

POST/v1/recruitment/roles

Permission: recruit.manage
Module: recruitment
Answers: 201

Request body JSON

titlestringrequired
1–120 characters
summarystringoptionalcan be null
Up to 300 characters
descriptionstringoptionalcan be null
Up to 20000 characters
areastringoptionalcan be null
Up to 120 characters
hoursstringoptionalcan be null
Up to 120 characters
paystringoptionalcan be null
Up to 120 characters
employmentTypeenumoptional
One of "employed", "self_employed" · Default "employed"
statusenumoptional
One of "draft", "open", "closed" · Default "draft"
closesOndateoptionalcan be null
YYYY-MM-DD
slugstringoptionalcan be null
Matches ^[a-z0-9]+(?:-[a-z0-9]+)*$ · Up to 80 characters

Response object

iduuidrequired
titlestringrequired
slugstringrequired
summarystringrequiredcan be null
descriptionstringrequiredcan be null
areastringrequiredcan be null
hoursstringrequiredcan be null
paystringrequiredcan be null
employmentTypeenumrequired
One of "employed", "self_employed"
statusenumrequired
One of "draft", "open", "closed"
closesOndaterequiredcan be null
YYYY-MM-DD
applicantsintegerrequired
-9007199254740991 to 9007199254740991
openApplicantsintegerrequired
-9007199254740991 to 9007199254740991
createdAtstringrequired

curl -X POST "https://app.workscope.co.uk/v1/recruitment/roles" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "text",
    "summary": "text",
    "description": "Side gate code is on the key safe.",
    "area": "text",
    "hours": "text",
    "pay": "text",
    "employmentType": "employed",
    "status": "draft",
    "closesOn": "2026-11-06",
    "slug": "example-slug"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "title": "text",
  "slug": "example-slug",
  "summary": "text",
  "description": "Side gate code is on the key safe.",
  "area": "text",
  "hours": "text",
  "pay": "text",
  "employmentType": "employed",
  "status": "draft",
  "closesOn": "2026-11-06",
  "applicants": -9007199254740991,
  "openApplicants": -9007199254740991,
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Change a role, open it or close it

PATCH/v1/recruitment/roles/{id}

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

titlestringoptional
1–120 characters
summarystringoptionalcan be null
Up to 300 characters
descriptionstringoptionalcan be null
Up to 20000 characters
areastringoptionalcan be null
Up to 120 characters
hoursstringoptionalcan be null
Up to 120 characters
paystringoptionalcan be null
Up to 120 characters
employmentTypeenumoptional
One of "employed", "self_employed" · Default "employed"
statusenumoptional
One of "draft", "open", "closed" · Default "draft"
closesOndateoptionalcan be null
YYYY-MM-DD
slugstringoptionalcan be null
Matches ^[a-z0-9]+(?:-[a-z0-9]+)*$ · Up to 80 characters

Response object

iduuidrequired
titlestringrequired
slugstringrequired
summarystringrequiredcan be null
descriptionstringrequiredcan be null
areastringrequiredcan be null
hoursstringrequiredcan be null
paystringrequiredcan be null
employmentTypeenumrequired
One of "employed", "self_employed"
statusenumrequired
One of "draft", "open", "closed"
closesOndaterequiredcan be null
YYYY-MM-DD
applicantsintegerrequired
-9007199254740991 to 9007199254740991
openApplicantsintegerrequired
-9007199254740991 to 9007199254740991
createdAtstringrequired

curl -X PATCH "https://app.workscope.co.uk/v1/recruitment/roles/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "text",
    "summary": "text",
    "description": "Side gate code is on the key safe.",
    "area": "text",
    "hours": "text",
    "pay": "text",
    "employmentType": "employed",
    "status": "draft",
    "closesOn": "2026-11-06",
    "slug": "example-slug"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "title": "text",
  "slug": "example-slug",
  "summary": "text",
  "description": "Side gate code is on the key safe.",
  "area": "text",
  "hours": "text",
  "pay": "text",
  "employmentType": "employed",
  "status": "draft",
  "closesOn": "2026-11-06",
  "applicants": -9007199254740991,
  "openApplicants": -9007199254740991,
  "createdAt": "2026-11-06T09:30:00.000Z"
}

Delete a role nobody has applied for (close it otherwise)

DELETE/v1/recruitment/roles/{id}

Permission: recruit.manage
Module: recruitment
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

curl -X DELETE "https://app.workscope.co.uk/v1/recruitment/roles/ID" \
  -H "Authorization: Bearer wsk_your_key_here"

Example response

{
  "ok": true
}