API reference

Custom fields

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

On this page

Booking templates (Xota's task templates): a name and its own booking fields

GET/v1/booking-templates

Permission: customFields.view
Answers: 200

Parameters

Name	In	Kind
`archived`	query	enum	One of `true`, `false`, `all` · Default `"false"`

Response array of object

iduuidrequired
namestringrequired
descriptionstringrequiredcan be null
durationMinutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
pricePenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
fieldDefaultsobjectrequired
checklistarray of objectrequired
- iduuidrequired
- labelstringrequired
- instructionstringrequiredcan be null
- kindenumrequired
  One of "tick", "text", "textarea", "number", "date", "time", "checkbox", "select", "photo"
- unitstringrequiredcan be null
- optionsarray of stringrequired
- askCommentbooleanrequired
- requiredbooleanrequired
- visibleToClientsbooleanrequired
archivedbooleanrequired
inUseintegerrequired
-9007199254740991 to 9007199254740991
fieldsarray of objectrequired
- iduuidrequired
- entityenumrequired
  One of "client", "project", "booking", "team_member"
- templateIduuidrequiredcan be null
- labelstringrequired
- slugstringrequired
- typeenumrequired
  One of "text", "textarea", "number", "date", "checkbox", "select", "address"
- optionsarray of stringrequired
- requiredbooleanrequired
- showInListbooleanrequired
- visibleToOperativesbooleanrequired
- visibleToClientsbooleanrequired
- positionintegerrequired
  -9007199254740991 to 9007199254740991
- archivedbooleanrequired

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

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "name": "Harbourside Dental",
    "description": "Side gate code is on the key safe.",
    "durationMinutes": 120,
    "pricePence": 4500,
    "fieldDefaults": {},
    "checklist": [
      {
        "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "label": "text",
        "instruction": "text",
        "kind": "tick",
        "unit": "text",
        "options": [
          "text"
        ],
        "askComment": false,
        "required": false,
        "visibleToClients": false
      }
    ],
    "archived": false,
    "inUse": -9007199254740991,
    "fields": [
      {
        "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
        "entity": "client",
        "templateId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "label": "text",
        "slug": "example-slug",
        "type": "text",
        "options": [
          "text"
        ],
        "required": false,
        "showInList": false,
        "visibleToOperatives": false,
        "visibleToClients": false,
        "position": -9007199254740991,
        "archived": false
      }
    ]
  }
]

Add a booking template

POST/v1/booking-templates

Permission: customFields.manage
Answers: 201

Request body JSON

namestringrequired
1–200 characters
descriptionstringoptionalcan be null
Up to 5000 characters
durationMinutesintegeroptionalcan be null
1 to 10080
pricePenceintegeroptionalcan be null
0 to 100000000
fieldDefaultsobjectoptional
checklistarray of objectoptional
Up to 50 items
- iduuidoptional
- labelstringrequired
  1–200 characters
- instructionstringoptionalcan be null
  Up to 1000 characters
- kindenumoptional
  One of "tick", "text", "textarea", "number", "date", "time", "checkbox", "select", "photo" · Default "tick"
- unitstringoptionalcan be null
  Up to 20 characters
- optionsarray of stringoptional
  Up to 30 items · Default []
- askCommentbooleanoptional
  Default false
- requiredbooleanoptional
  Default false
- visibleToClientsbooleanoptional
  Default false

Response object

iduuidrequired
namestringrequired
descriptionstringrequiredcan be null
durationMinutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
pricePenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
fieldDefaultsobjectrequired
checklistarray of objectrequired
- iduuidrequired
- labelstringrequired
- instructionstringrequiredcan be null
- kindenumrequired
  One of "tick", "text", "textarea", "number", "date", "time", "checkbox", "select", "photo"
- unitstringrequiredcan be null
- optionsarray of stringrequired
- askCommentbooleanrequired
- requiredbooleanrequired
- visibleToClientsbooleanrequired
archivedbooleanrequired
inUseintegerrequired
-9007199254740991 to 9007199254740991
fieldsarray of objectrequired
- iduuidrequired
- entityenumrequired
  One of "client", "project", "booking", "team_member"
- templateIduuidrequiredcan be null
- labelstringrequired
- slugstringrequired
- typeenumrequired
  One of "text", "textarea", "number", "date", "checkbox", "select", "address"
- optionsarray of stringrequired
- requiredbooleanrequired
- showInListbooleanrequired
- visibleToOperativesbooleanrequired
- visibleToClientsbooleanrequired
- positionintegerrequired
  -9007199254740991 to 9007199254740991
- archivedbooleanrequired

curl -X POST "https://app.workscope.co.uk/v1/booking-templates" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "description": "Side gate code is on the key safe.",
    "durationMinutes": 120,
    "pricePence": 4500,
    "fieldDefaults": {},
    "checklist": [
      {
        "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "label": "text",
        "instruction": "text",
        "kind": "tick",
        "unit": "text",
        "options": [
          "text"
        ],
        "askComment": false,
        "required": false,
        "visibleToClients": false
      }
    ]
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "description": "Side gate code is on the key safe.",
  "durationMinutes": 120,
  "pricePence": 4500,
  "fieldDefaults": {},
  "checklist": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "label": "text",
      "instruction": "text",
      "kind": "tick",
      "unit": "text",
      "options": [
        "text"
      ],
      "askComment": false,
      "required": false,
      "visibleToClients": false
    }
  ],
  "archived": false,
  "inUse": -9007199254740991,
  "fields": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "entity": "client",
      "templateId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "label": "text",
      "slug": "example-slug",
      "type": "text",
      "options": [
        "text"
      ],
      "required": false,
      "showInList": false,
      "visibleToOperatives": false,
      "visibleToClients": false,
      "position": -9007199254740991,
      "archived": false
    }
  ]
}

Rename or archive a booking template

PATCH/v1/booking-templates/{id}

Permission: customFields.manage
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

namestringoptional
1–200 characters
descriptionstringoptionalcan be null
Up to 5000 characters
durationMinutesintegeroptionalcan be null
1 to 10080
pricePenceintegeroptionalcan be null
0 to 100000000
fieldDefaultsobjectoptional
checklistarray of objectoptional
Up to 50 items
- iduuidoptional
- labelstringrequired
  1–200 characters
- instructionstringoptionalcan be null
  Up to 1000 characters
- kindenumoptional
  One of "tick", "text", "textarea", "number", "date", "time", "checkbox", "select", "photo" · Default "tick"
- unitstringoptionalcan be null
  Up to 20 characters
- optionsarray of stringoptional
  Up to 30 items · Default []
- askCommentbooleanoptional
  Default false
- requiredbooleanoptional
  Default false
- visibleToClientsbooleanoptional
  Default false
archivedbooleanoptional

Response object

iduuidrequired
namestringrequired
descriptionstringrequiredcan be null
durationMinutesintegerrequiredcan be null
-9007199254740991 to 9007199254740991
pricePenceintegerrequiredcan be null
-9007199254740991 to 9007199254740991
fieldDefaultsobjectrequired
checklistarray of objectrequired
- iduuidrequired
- labelstringrequired
- instructionstringrequiredcan be null
- kindenumrequired
  One of "tick", "text", "textarea", "number", "date", "time", "checkbox", "select", "photo"
- unitstringrequiredcan be null
- optionsarray of stringrequired
- askCommentbooleanrequired
- requiredbooleanrequired
- visibleToClientsbooleanrequired
archivedbooleanrequired
inUseintegerrequired
-9007199254740991 to 9007199254740991
fieldsarray of objectrequired
- iduuidrequired
- entityenumrequired
  One of "client", "project", "booking", "team_member"
- templateIduuidrequiredcan be null
- labelstringrequired
- slugstringrequired
- typeenumrequired
  One of "text", "textarea", "number", "date", "checkbox", "select", "address"
- optionsarray of stringrequired
- requiredbooleanrequired
- showInListbooleanrequired
- visibleToOperativesbooleanrequired
- visibleToClientsbooleanrequired
- positionintegerrequired
  -9007199254740991 to 9007199254740991
- archivedbooleanrequired

curl -X PATCH "https://app.workscope.co.uk/v1/booking-templates/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Harbourside Dental",
    "description": "Side gate code is on the key safe.",
    "durationMinutes": 120,
    "pricePence": 4500,
    "fieldDefaults": {},
    "checklist": [
      {
        "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
        "label": "text",
        "instruction": "text",
        "kind": "tick",
        "unit": "text",
        "options": [
          "text"
        ],
        "askComment": false,
        "required": false,
        "visibleToClients": false
      }
    ],
    "archived": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "name": "Harbourside Dental",
  "description": "Side gate code is on the key safe.",
  "durationMinutes": 120,
  "pricePence": 4500,
  "fieldDefaults": {},
  "checklist": [
    {
      "id": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
      "label": "text",
      "instruction": "text",
      "kind": "tick",
      "unit": "text",
      "options": [
        "text"
      ],
      "askComment": false,
      "required": false,
      "visibleToClients": false
    }
  ],
  "archived": false,
  "inUse": -9007199254740991,
  "fields": [
    {
      "id": "b7e6d5c4-3b2a-4190-8f7e-6d5c4b3a2918",
      "entity": "client",
      "templateId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
      "label": "text",
      "slug": "example-slug",
      "type": "text",
      "options": [
        "text"
      ],
      "required": false,
      "showInList": false,
      "visibleToOperatives": false,
      "visibleToClients": false,
      "position": -9007199254740991,
      "archived": false
    }
  ]
}

Delete a booking template nothing uses (archive it otherwise)

DELETE/v1/booking-templates/{id}

Permission: customFields.manage
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

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

Example response

{
  "ok": true
}

The company's own fields on clients, projects and bookings (operatives get the booking fields marked for them)

GET/v1/custom-fields

Permission: customFields.view
Answers: 200

Parameters

Name	In	Kind
`entity`	query	enum	One of `client`, `project`, `booking`, `team_member`
`templateId`	query	uuid
`archived`	query	enum	One of `true`, `false`, `all` · Default `"false"`

Response array of object

iduuidrequired
entityenumrequired
One of "client", "project", "booking", "team_member"
templateIduuidrequiredcan be null
labelstringrequired
slugstringrequired
typeenumrequired
One of "text", "textarea", "number", "date", "checkbox", "select", "address"
optionsarray of stringrequired
requiredbooleanrequired
showInListbooleanrequired
visibleToOperativesbooleanrequired
visibleToClientsbooleanrequired
positionintegerrequired
-9007199254740991 to 9007199254740991
archivedbooleanrequired

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

Example response

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "entity": "client",
    "templateId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "label": "text",
    "slug": "example-slug",
    "type": "text",
    "options": [
      "text"
    ],
    "required": false,
    "showInList": false,
    "visibleToOperatives": false,
    "visibleToClients": false,
    "position": -9007199254740991,
    "archived": false
  }
]

Add a field

POST/v1/custom-fields

Permission: customFields.manage
Answers: 201

Request body JSON

labelstringrequired
1–100 characters
typeenumrequired
One of "text", "textarea", "number", "date", "checkbox", "select", "address"
optionsarray of stringoptional
Up to 100 items · Default []
requiredbooleanoptional
Default false
showInListbooleanoptional
Default false
visibleToOperativesbooleanoptional
visibleToClientsbooleanoptional
Default false
positionintegeroptional
0 to 10000
entityenumrequired
One of "client", "project", "booking", "team_member"
templateIduuidoptionalcan be null

Response object

iduuidrequired
entityenumrequired
One of "client", "project", "booking", "team_member"
templateIduuidrequiredcan be null
labelstringrequired
slugstringrequired
typeenumrequired
One of "text", "textarea", "number", "date", "checkbox", "select", "address"
optionsarray of stringrequired
requiredbooleanrequired
showInListbooleanrequired
visibleToOperativesbooleanrequired
visibleToClientsbooleanrequired
positionintegerrequired
-9007199254740991 to 9007199254740991
archivedbooleanrequired

curl -X POST "https://app.workscope.co.uk/v1/custom-fields" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "text",
    "type": "text",
    "options": [
      "text"
    ],
    "required": false,
    "showInList": false,
    "visibleToOperatives": false,
    "visibleToClients": false,
    "position": 0,
    "entity": "client",
    "templateId": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41"
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "entity": "client",
  "templateId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "label": "text",
  "slug": "example-slug",
  "type": "text",
  "options": [
    "text"
  ],
  "required": false,
  "showInList": false,
  "visibleToOperatives": false,
  "visibleToClients": false,
  "position": -9007199254740991,
  "archived": false
}

Change a field (its type and slug stay), or archive it

PATCH/v1/custom-fields/{id}

Permission: customFields.manage
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Request body JSON

labelstringoptional
1–100 characters
optionsarray of stringoptional
Up to 100 items
requiredbooleanoptional
showInListbooleanoptional
visibleToOperativesbooleanoptional
visibleToClientsbooleanoptional
positionintegeroptional
0 to 10000
archivedbooleanoptional

Response object

iduuidrequired
entityenumrequired
One of "client", "project", "booking", "team_member"
templateIduuidrequiredcan be null
labelstringrequired
slugstringrequired
typeenumrequired
One of "text", "textarea", "number", "date", "checkbox", "select", "address"
optionsarray of stringrequired
requiredbooleanrequired
showInListbooleanrequired
visibleToOperativesbooleanrequired
visibleToClientsbooleanrequired
positionintegerrequired
-9007199254740991 to 9007199254740991
archivedbooleanrequired

curl -X PATCH "https://app.workscope.co.uk/v1/custom-fields/ID" \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "text",
    "options": [
      "text"
    ],
    "required": false,
    "showInList": false,
    "visibleToOperatives": false,
    "visibleToClients": false,
    "position": 0,
    "archived": false
  }'

Example response

{
  "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
  "entity": "client",
  "templateId": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "label": "text",
  "slug": "example-slug",
  "type": "text",
  "options": [
    "text"
  ],
  "required": false,
  "showInList": false,
  "visibleToOperatives": false,
  "visibleToClients": false,
  "position": -9007199254740991,
  "archived": false
}

Delete a field nothing has a value for (archive it otherwise)

DELETE/v1/custom-fields/{id}

Permission: customFields.manage
Answers: 200

Parameters

Name	In	Kind
`id`	path	uuidrequired

Response object

okconstantrequired
Always true

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

Example response

{
  "ok": true
}