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

# Companies

A company is an account your workspace holds. Workloom matches companies on their domain, so the same business is not added twice. Size, location and industry come from Workloom’s data.

Scopes: `companies:read`, `companies:write`.

## The company object

- `id` (string): The company’s id.
- `name` (string, nullable): Company name.
- `domain` (string, nullable): Website domain.
- `industry` (string, nullable): Industry.
- `employee_count` (integer, nullable): Number of employees, when known exactly.
- `employee_range` (string, nullable): Size band, for example "51-200".
- `location` (object, nullable): Headquarters, as far as we know.
- `linkedin_url` (string, nullable): LinkedIn company page.
- `owner_seat_id` (string, nullable): The teammate who owns this account. Null when nobody does.
- `tags` (array of string): Tags on the company.
- `custom_fields` (object): Your own fields (Settings › Data model), by key. `GET /custom-fields` lists their keys, labels and types. A field with no value is left out.
- `created_at` (timestamp): When the company was added.
- `updated_at` (timestamp): When the company last changed.

```json
{
  "id": "66f19b77e4b0a1b2c3d4a1b2",
  "name": "Brightline",
  "domain": "brightline.example",
  "industry": "Logistics",
  "employee_count": 420,
  "employee_range": "201-500",
  "location": {
    "city": "Bengaluru",
    "state": "Karnataka",
    "country": "India"
  },
  "linkedin_url": "https://www.linkedin.com/company/brightline",
  "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
  "tags": [
    "series-b"
  ],
  "custom_fields": {
    "segment": "Mid-market"
  },
  "created_at": "2026-09-18T07:30:00.000Z",
  "updated_at": "2026-10-02T16:20:31.000Z"
}
```

## Endpoints

### List companies

`GET /companies`

Companies in your workspace, oldest first unless you `sort`. A key acting for one person sees the companies that person owns or whose people they can see.

Scope: `companies:read`

**Query parameters**

- `domain` (string): Only the company with this domain.
- `sort` (string): Order by one field, oldest or smallest first; put `-` in front for newest or largest first. Empty values come first ascending and last descending. Default: oldest first. Keep the same `sort` while you follow `next_cursor`.
- `limit` (integer): How many to return, 1 to 100. Default 25.
- `cursor` (string): The `next_cursor` from the previous page.

**Request**

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

```javascript
const res = await fetch("https://api.useworkloom.com/api/public/v1/companies?limit=25", {
  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/companies?limit=25",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
)
data = res.json()
```

**Response (sample, 200)**

```json
{
  "data": [
    {
      "id": "66f19b77e4b0a1b2c3d4a1b2",
      "name": "Brightline",
      "domain": "brightline.example",
      "industry": "Logistics",
      "employee_count": 420,
      "employee_range": "201-500",
      "location": {
        "city": "Bengaluru",
        "state": "Karnataka",
        "country": "India"
      },
      "linkedin_url": "https://www.linkedin.com/company/brightline",
      "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
      "tags": [
        "series-b"
      ],
      "custom_fields": {
        "segment": "Mid-market"
      },
      "created_at": "2026-09-18T07:30:00.000Z",
      "updated_at": "2026-10-02T16:20:31.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "66f19b77e4b0a1b2c3d4a1b2"
}
```

**Errors**

- 400: `invalid_request`, `unknown_fields`, `reason_required` or `unsupported_version`.
- 401: `authentication_required` or `invalid_key`.
- 403: `missing_scope`, `forbidden`, `seat_inactive` or `organisation_inactive`.
- 429: `rate_limited`. Wait `Retry-After` seconds.
- 500: `internal_error`.

### Add a company

`POST /companies`

Adds a company, checked for duplicates exactly as adding one in Workloom is: the same domain is refused, and the same name needs `force: true`. A key acting for a person makes it theirs.

Scope: `companies:write`

**Header parameters**

- `Idempotency-Key` (string): Any unique string, up to 255 characters. Send the same key when you retry and the request runs once; the first answer comes back with `Idempotent-Replayed: true`. Kept 24 hours.

**Body parameters**

- `name` (string, required): Company name.
- `domain` (string, nullable): Website or domain.
- `industry` (string, nullable): Industry.
- `custom_fields` (object): Your own fields by key (`GET /custom-fields`). Each value is checked against its field’s type, and everything is checked before anything is saved.
- `force` (boolean): Add it even though a company with the same name exists.

**Request**

```bash
curl -X POST "https://api.useworkloom.com/api/public/v1/companies" \
  -H "Authorization: Bearer $WORKLOOM_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "name": "Brightline",
  "domain": "brightline.example",
  "industry": "Logistics"
}'
```

```javascript
const res = await fetch("https://api.useworkloom.com/api/public/v1/companies", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({
    "name": "Brightline",
    "domain": "brightline.example",
    "industry": "Logistics"
  })
});
const data = await res.json();
```

```python
import os, uuid, requests

res = requests.post(
    "https://api.useworkloom.com/api/public/v1/companies",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
      "name": "Brightline",
      "domain": "brightline.example",
      "industry": "Logistics"
    },
)
data = res.json()
```

**Response (sample, 201)**

```json
{
  "data": {
    "id": "66f19b77e4b0a1b2c3d4a1b2",
    "name": "Brightline",
    "domain": "brightline.example",
    "industry": "Logistics",
    "employee_count": 420,
    "employee_range": "201-500",
    "location": {
      "city": "Bengaluru",
      "state": "Karnataka",
      "country": "India"
    },
    "linkedin_url": "https://www.linkedin.com/company/brightline",
    "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
    "tags": [
      "series-b"
    ],
    "custom_fields": {
      "segment": "Mid-market"
    },
    "created_at": "2026-09-18T07:30:00.000Z",
    "updated_at": "2026-10-02T16:20:31.000Z"
  },
  "livemode": true
}
```

**Errors**

- 400: `invalid_request`, `unknown_fields`, `reason_required` or `unsupported_version`.
- 401: `authentication_required` or `invalid_key`.
- 403: `missing_scope`, `forbidden`, `seat_inactive` or `organisation_inactive`.
- 409: `duplicate`, `conflict` or `idempotency_key_in_use`.
- 422: `idempotency_key_reused`.
- 429: `rate_limited`. Wait `Retry-After` seconds.
- 500: `internal_error`.

### Get a company

`GET /companies/{id}`

Returns one company. A company the key cannot reach answers `not_found`.

Scope: `companies:read`

**Path parameters**

- `id` (string, required): The company’s id.

**Request**

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

```javascript
const res = await fetch("https://api.useworkloom.com/api/public/v1/companies/66f19b77e4b0a1b2c3d4a1b2", {
  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/companies/66f19b77e4b0a1b2c3d4a1b2",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
)
data = res.json()
```

**Response (sample, 200)**

```json
{
  "data": {
    "id": "66f19b77e4b0a1b2c3d4a1b2",
    "name": "Brightline",
    "domain": "brightline.example",
    "industry": "Logistics",
    "employee_count": 420,
    "employee_range": "201-500",
    "location": {
      "city": "Bengaluru",
      "state": "Karnataka",
      "country": "India"
    },
    "linkedin_url": "https://www.linkedin.com/company/brightline",
    "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
    "tags": [
      "series-b"
    ],
    "custom_fields": {
      "segment": "Mid-market"
    },
    "created_at": "2026-09-18T07:30:00.000Z",
    "updated_at": "2026-10-02T16:20:31.000Z"
  }
}
```

**Errors**

- 400: `invalid_request`, `unknown_fields`, `reason_required` or `unsupported_version`.
- 401: `authentication_required` or `invalid_key`.
- 403: `missing_scope`, `forbidden`, `seat_inactive` or `organisation_inactive`.
- 404: `not_found`.
- 429: `rate_limited`. Wait `Retry-After` seconds.
- 500: `internal_error`.

### Update a company

`PATCH /companies/{id}`

Changes how your workspace holds the company: its owner and its tags. Size, location and the rest come from Workloom’s data and are not set over the API.

Scope: `companies:write`

**Path parameters**

- `id` (string, required): The company’s id.

**Body parameters**

- `tags` (array of string): Replaces the tags.
- `owner_seat_id` (string, nullable): Hand the account to a teammate. Null leaves it unowned.
- `custom_fields` (object): Your own fields by key (`GET /custom-fields`). Each value is checked against its field’s type, and everything is checked before anything is saved.

**Request**

```bash
curl -X PATCH "https://api.useworkloom.com/api/public/v1/companies/66f19b77e4b0a1b2c3d4a1b2" \
  -H "Authorization: Bearer $WORKLOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
  "tags": [
    "series-b",
    "expansion"
  ]
}'
```

```javascript
const res = await fetch("https://api.useworkloom.com/api/public/v1/companies/66f19b77e4b0a1b2c3d4a1b2", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
    "tags": [
      "series-b",
      "expansion"
    ]
  })
});
const data = await res.json();
```

```python
import os, requests

res = requests.patch(
    "https://api.useworkloom.com/api/public/v1/companies/66f19b77e4b0a1b2c3d4a1b2",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
    json={
      "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
      "tags": [
        "series-b",
        "expansion"
      ]
    },
)
data = res.json()
```

**Response (sample, 200)**

```json
{
  "data": {
    "id": "66f19b77e4b0a1b2c3d4a1b2",
    "name": "Brightline",
    "domain": "brightline.example",
    "industry": "Logistics",
    "employee_count": 420,
    "employee_range": "201-500",
    "location": {
      "city": "Bengaluru",
      "state": "Karnataka",
      "country": "India"
    },
    "linkedin_url": "https://www.linkedin.com/company/brightline",
    "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
    "tags": [
      "series-b"
    ],
    "custom_fields": {
      "segment": "Mid-market"
    },
    "created_at": "2026-09-18T07:30:00.000Z",
    "updated_at": "2026-10-02T16:20:31.000Z"
  },
  "livemode": true
}
```

**Errors**

- 400: `invalid_request`, `unknown_fields`, `reason_required` or `unsupported_version`.
- 401: `authentication_required` or `invalid_key`.
- 403: `missing_scope`, `forbidden`, `seat_inactive` or `organisation_inactive`.
- 404: `not_found`.
- 409: `duplicate`, `conflict` or `idempotency_key_in_use`.
- 429: `rate_limited`. Wait `Retry-After` seconds.
- 500: `internal_error`.

### Search companies

`POST /companies/search`

Companies matching every filter, oldest first unless you `sort` (created_at, updated_at or employee_count), paged like the list. Searchable: name, domain, industry, employee_count, employee_range, location.city, location.country, owner_seat_id, tags, created_at, updated_at, and custom_fields.<key>. Operators as for contacts.

Scope: `companies:read`

**Body parameters**

- `filters` (array of SearchFilter): Up to 20 filters. All must match.
- `limit` (integer): How many to return, 1 to 100. Default 25.
- `cursor` (string, nullable): The `next_cursor` from the previous page.
- `sort` (string, nullable): Order by one field, as `sort` on the list: `-` in front for newest or largest first. Keep the same `sort` while you follow `next_cursor`.

**Request**

```bash
curl -X POST "https://api.useworkloom.com/api/public/v1/companies/search" \
  -H "Authorization: Bearer $WORKLOOM_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "filters": [
    {
      "field": "custom_fields.segment",
      "op": "eq",
      "value": "Mid-market"
    }
  ]
}'
```

```javascript
const res = await fetch("https://api.useworkloom.com/api/public/v1/companies/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.WORKLOOM_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "filters": [
      {
        "field": "custom_fields.segment",
        "op": "eq",
        "value": "Mid-market"
      }
    ]
  })
});
const data = await res.json();
```

```python
import os, requests

res = requests.post(
    "https://api.useworkloom.com/api/public/v1/companies/search",
    headers={"Authorization": f"Bearer {os.environ['WORKLOOM_KEY']}"},
    json={
      "filters": [
        {
          "field": "custom_fields.segment",
          "op": "eq",
          "value": "Mid-market"
        }
      ]
    },
)
data = res.json()
```

**Response (sample, 200)**

```json
{
  "data": [
    {
      "id": "66f19b77e4b0a1b2c3d4a1b2",
      "name": "Brightline",
      "domain": "brightline.example",
      "industry": "Logistics",
      "employee_count": 420,
      "employee_range": "201-500",
      "location": {
        "city": "Bengaluru",
        "state": "Karnataka",
        "country": "India"
      },
      "linkedin_url": "https://www.linkedin.com/company/brightline",
      "owner_seat_id": "66e0f1a2e4b0a1b2c3d40a0b",
      "tags": [
        "series-b"
      ],
      "custom_fields": {
        "segment": "Mid-market"
      },
      "created_at": "2026-09-18T07:30:00.000Z",
      "updated_at": "2026-10-02T16:20:31.000Z"
    }
  ],
  "has_more": true,
  "next_cursor": "66f19b77e4b0a1b2c3d4a1b2"
}
```

**Errors**

- 400: `invalid_request`, `unknown_fields`, `reason_required` or `unsupported_version`.
- 401: `authentication_required` or `invalid_key`.
- 403: `missing_scope`, `forbidden`, `seat_inactive` or `organisation_inactive`.
- 409: `duplicate`, `conflict` or `idempotency_key_in_use`.
- 429: `rate_limited`. Wait `Retry-After` seconds.
- 500: `internal_error`.