Getting started

Everything you can do in Workscope, you can do through its API. The web app and the team app use this same API, so nothing is held back.

1. Make an API key

In Workscope, go to Settings › API keys and choose Make a key. Give it a name you'll recognise later, such as "Accounts sync", and pick what it may do (its role).

The key is shown once. Copy it somewhere safe, such as your password manager or your server's secrets. If you lose it, stop it and make a new one.

Only an owner, or an admin who can see company settings, can make keys.

2. Send your first request

Every request goes to https://app.workscope.co.uk, with your key in the Authorization header. To check the key works, ask who it is:

curl https://app.workscope.co.uk/v1/api-keys/current \
  -H "Authorization: Bearer wsk_your_key_here"

That answers with the key's name, its role and the company it works for. Then, for example, list your clients:

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

You get back JSON: a list of clients, each with its id, name, contact details and status.

[
  {
    "id": "3f2a9c1e-6b4d-4e8a-9f1c-2d7b5a0e8c41",
    "name": "Harbourside Dental",
    "email": "office@example.co.uk",
    "status": "live",
    ...
  }
]

3. Make a change

Changes send JSON in the body. This adds a client:

curl https://app.workscope.co.uk/v1/clients \
  -H "Authorization: Bearer wsk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name": "Clifton Lettings"}'

Where next

• Keys and roles: what a key may and may not do.
• Errors: what comes back when something is wrong.
• Lists, dates and money: how dates, times and amounts are written.
• The API reference: every request, area by area.

The whole API is also described in one machine-readable file, openapi.json (OpenAPI 3.1). Most tools can read it to make a client library for you.