<!-- Source: https://useworkloom.com/dev/ · Workloom API v1 -->

# The Workloom API

Read and write the contacts, companies and deals in your workspace, with their notes, tasks and lists. Put contacts into outreach, read the revenue report, and get a signed webhook when something happens. One key, one base URL, JSON in and out.

Base URL: `https://api.useworkloom.com/api/public/v1`

**GET / (sample response)**

```json
{
  "organisation": {
    "id": "66d0a0b0e4b0a1b2c3d40001",
    "name": "Brightpath"
  },
  "key": {
    "name": "Warehouse sync",
    "scopes": [
      "contacts:read",
      "companies:read",
      "deals:read",
      "reports:read",
      "team:read",
      "activity:read",
      "lists:read",
      "creative:read"
    ],
    "mode": "test"
  },
  "acts_as": "the whole organisation",
  "livemode": false,
  "limits": {
    "requests_per_minute": 300,
    "max_page_size": 100
  },
  "docs": {
    "openapi": "/api/public/v1/openapi.json"
  },
  "resources": {
    "contacts": "GET /api/public/v1/contacts",
    "create_deal": "POST /api/public/v1/deals",
    "…": "…"
  }
}
```

## Your first call

- **Make a key**: In Workloom, open Settings › API and webhooks and choose New key. Start with a test key: it reads your records and changes nothing.
- **Call GET /**: Send the key as a bearer token. The answer names the workspace, the key, its scopes and whether it is live or test.
- **Make your first write**: Add a contact with `POST /contacts`. A test key answers with what would be saved. A live key saves it, and it is in Workloom straight away.

**Check your key**

```bash
curl "https://api.useworkloom.com/api/public/v1/" \
  -H "Authorization: Bearer $WORKLOOM_KEY"
```

```javascript
const res = await fetch("https://api.useworkloom.com/api/public/v1/", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`
  }
});
const data = await res.json();
```

```python
import os, requests

res = requests.get(
    "https://api.useworkloom.com/api/public/v1/",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
)
data = res.json()
```

**Add your first contact**

```bash
curl -X POST "https://api.useworkloom.com/api/public/v1/contacts" \
  -H "Authorization: Bearer $WORKLOOM_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "first_name": "Priya",
  "last_name": "Nair",
  "email": "priya@brightline.example"
}'
```

```javascript
const res = await fetch("https://api.useworkloom.com/api/public/v1/contacts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({
    "first_name": "Priya",
    "last_name": "Nair",
    "email": "priya@brightline.example"
  })
});
const data = await res.json();
```

```python
import os, uuid, requests

res = requests.post(
    "https://api.useworkloom.com/api/public/v1/contacts",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
      "first_name": "Priya",
      "last_name": "Nair",
      "email": "priya@brightline.example"
    },
)
data = res.json()
```

## Playground

Pick an endpoint, edit the body, and the code changes as you type. Send answers with a sample, including the error the API gives for a bad body. Nothing is sent to Workloom.

## What’s in the API

- [Contacts](https://useworkloom.com/dev/contacts/): 7 endpoints
- [Companies](https://useworkloom.com/dev/companies/): 5 endpoints
- [Deals](https://useworkloom.com/dev/deals/): 7 endpoints
- [Reports](https://useworkloom.com/dev/reports/): 1 endpoint
- [Pipelines, team and fields](https://useworkloom.com/dev/workspace/): 3 endpoints
- [Timelines, notes and tasks](https://useworkloom.com/dev/activity/): 9 endpoints
- [Lists](https://useworkloom.com/dev/lists/): 5 endpoints
- [Outreach](https://useworkloom.com/dev/outreach/): 3 endpoints
- [Documents, videos and designs](https://useworkloom.com/dev/creative/): 5 endpoints

- [Webhooks](https://useworkloom.com/dev/webhooks/): Signed POSTs to your server when someone replies, a meeting is booked, a deal moves and more.
- [Changelog](https://useworkloom.com/dev/changelog/): What changed in the API, and when.

## Versions

New fields, endpoints, events and error codes arrive without notice and reach every version, so ignore what you do not know. A change that would break an integration comes as a new dated version, and reaches nobody until they ask for it. The latest is `2026-10-07`.

Every key and every webhook endpoint is pinned to the version that was current when it was made. A request without the `Workloom-Version` header is answered in its key’s version, and a delivery is shaped in its endpoint’s version. To try a newer version, send `Workloom-Version: <version>` on a request; to move an endpoint, change its `workloom_version`. Every answer and every delivery says its version in the `Workloom-Version` header. An old version stops working only after 6 months’ notice in the [changelog](https://useworkloom.com/dev/changelog/). The path, `/api/public/v1`, changes only for a redesign of the whole API.

| Version | What it is |
| --- | --- |
| `2026-10-07` | The first dated version: the API as it was on 7 October 2026. Every key and endpoint made before then is on it. |

### Headers you send

| Header | Example | What it does |
| --- | --- | --- |
| `Authorization` | `Bearer wl_live_…` | Your key. Needed on every call except `/openapi.json`. |
| `X-API-Key` | `wl_live_…` | The same key, if you cannot send `Authorization`. |
| `Idempotency-Key` | any unique string | Makes a POST safe to retry. Kept 24 hours. |
| `Content-Type` | `application/json` | Needed when you send a body. |
| `Workloom-Version` | `2026-10-07` | Answers this request in that version. Leave it out to use your key’s. |

### Headers you get back

| Header | What it says |
| --- | --- |
| `Workloom-Mode` | `live` or `test`: which kind of key made the request. |
| `Workloom-Version` | The version this answer is in. |
| `X-RateLimit-Limit` | Requests a minute the key may make. |
| `X-RateLimit-Remaining` | Requests left this minute. |
| `Retry-After` | Only on a `429`: seconds to wait. |
| `Idempotent-Replayed` | `true` when the answer is the stored one for a repeated `Idempotency-Key`. |

The whole API is also described in an [OpenAPI 3.1 file](https://api.useworkloom.com/api/public/v1/openapi.json), which needs no key.