---
title: Prospect Companies
description: Create, read, update and delete the companies you're prospecting.
product: signal
section: api
order: 15
---

# Prospect Companies

A Prospect Company is a company you're prospecting that isn't yet an Account. [Prospect contacts](prospects.md) link to one through their `lead_company_id`.

These endpoints use the `prospects:read` and `prospects:write` scopes.

## The Prospect Company object

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | 25-character ID. |
| `name` | string | |
| `industry` | string or null | |
| `size` | string or null | Free text, such as `51-200`. |
| `revenue` | string or null | Free text, such as `$10M-$50M`. |
| `location` | string or null | |
| `website` | string or null | |
| `phone` | string or null | |
| `address` | string or null | |
| `notes` | string or null | |
| `source_id` | string or null | A [prospect source](prospect-sources.md) ID. |
| `owner_id` | string or null | User ID of the person in **Assigned To**. |
| `archived_at` | string or null | When it was archived. Read-only. |
| `created_at` | string | ISO 8601 timestamp. |
| `updated_at` | string | ISO 8601 timestamp. |

```json
{
  "id": "cm3k9x2p10004qz8f7h2d1a6b",
  "name": "Fabrikam Logistics",
  "industry": "Logistics",
  "size": "51-200",
  "revenue": "$10M-$50M",
  "location": "Newark, NJ",
  "website": "https://fabrikam.example",
  "phone": null,
  "address": null,
  "notes": null,
  "source_id": "rls_trade_show",
  "owner_id": "5b8d1f3a-7e2c-4a9b-b6d4-1c3e5f7a9b20",
  "archived_at": null,
  "created_at": "2026-11-12T09:30:00.000Z",
  "updated_at": "2026-11-12T09:30:00.000Z"
}
```

---

## List Prospect Companies

`GET /prospect-companies` · Scope: `prospects:read`

This list uses **offset** pagination, not cursors.

### Query parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | integer | No | Up to 200. Default 50. |
| `offset` | integer | No | Number of records to skip. Default 0. |

### Example

```bash
curl "https://crm.empiraa.app/api/v1/prospect-companies?limit=200&offset=0" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
async function allProspectCompanies(apiKey) {
  const all = [];
  let offset = 0;
  for (;;) {
    const res = await fetch(
      `https://crm.empiraa.app/api/v1/prospect-companies?limit=200&offset=${offset}`,
      { headers: { Authorization: `Bearer ${apiKey}` } },
    );
    const { data, meta } = await res.json();
    all.push(...data);
    if (!meta.hasMore) return all;
    offset += data.length;
  }
}
```

### Response `200`

```json
{
  "data": [ { "id": "cm3k9x2p10004qz8f7h2d1a6b", "name": "Fabrikam Logistics", "industry": "Logistics" } ],
  "meta": { "cursor": null, "total": 312, "limit": 200, "offset": 0, "hasMore": true },
  "error": null
}
```

(Shortened: each item is a full Prospect Company object.)

---

## Create a Prospect Company

`POST /prospect-companies` · Scope: `prospects:write`

### Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | Yes | Can't be blank. Leading and trailing spaces are trimmed. |
| `industry` | string or null | No | |
| `size` | string or null | No | |
| `revenue` | string or null | No | |
| `location` | string or null | No | |
| `website` | string or null | No | |
| `phone` | string or null | No | |
| `address` | string or null | No | |
| `notes` | string or null | No | |
| `source_id` | string or null | No | A [prospect source](prospect-sources.md) ID. |
| `owner_id` | string or null | No | **Assigned To**: an active user in the workspace. |

### Example

```bash
curl -X POST https://crm.empiraa.app/api/v1/prospect-companies \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Fabrikam Logistics", "industry": "Logistics", "website": "https://fabrikam.example"}'
```

```js
await fetch("https://crm.empiraa.app/api/v1/prospect-companies", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Fabrikam Logistics", industry: "Logistics", website: "https://fabrikam.example" }),
});
```

### Response `201`

The new [Prospect Company object](#the-prospect-company-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | `name` is missing or blank, or `owner_id` isn't a string or `null`. |
| 404 | `NOT_FOUND` | `owner_id` isn't an active user in the workspace. |

**Webhook events:** none.

---

## Get a Prospect Company

`GET /prospect-companies/{id}` · Scope: `prospects:read`

### Example

```bash
curl https://crm.empiraa.app/api/v1/prospect-companies/cm3k9x2p10004qz8f7h2d1a6b \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
await fetch("https://crm.empiraa.app/api/v1/prospect-companies/cm3k9x2p10004qz8f7h2d1a6b", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
```

### Response `200`

The [Prospect Company object](#the-prospect-company-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No Prospect Company with that ID in this workspace. |

---

## Update a Prospect Company

`PATCH /prospect-companies/{id}` · Scope: `prospects:write`

Send only the fields you want to change. Accepts the same fields as [create](#create-a-prospect-company); `owner_id` can be `null` for nobody.

### Example

```bash
curl -X PATCH https://crm.empiraa.app/api/v1/prospect-companies/cm3k9x2p10004qz8f7h2d1a6b \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"size": "201-500", "owner_id": null}'
```

```js
await fetch("https://crm.empiraa.app/api/v1/prospect-companies/cm3k9x2p10004qz8f7h2d1a6b", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ size: "201-500", owner_id: null }),
});
```

### Response `200`

The updated [Prospect Company object](#the-prospect-company-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | `owner_id` isn't a string or `null`. |
| 404 | `NOT_FOUND` | The Prospect Company or the user doesn't exist in this workspace. |

**Webhook events:** none.

---

## Delete a Prospect Company

`DELETE /prospect-companies/{id}` · Scope: `prospects:write`

Deletes the Prospect Company.

### Example

```bash
curl -X DELETE https://crm.empiraa.app/api/v1/prospect-companies/cm3k9x2p10004qz8f7h2d1a6b \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
await fetch("https://crm.empiraa.app/api/v1/prospect-companies/cm3k9x2p10004qz8f7h2d1a6b", {
  method: "DELETE",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
```

### Response `204`

No body.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No Prospect Company with that ID in this workspace. |

**Webhook events:** none.