---
title: Accounts
description: Create, read, update and deactivate Accounts, and record what each Account spends.
product: signal
section: api
order: 10
---

# Accounts

An Account is a company you sell to or work with. Contacts and Deals belong to an Account.

Account spend records track money an Account has spent (for example orders or invoices from another system), each with its own currency.

## The Account object

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | UUID. |
| `name` | string | |
| `legal_name` | string or null | |
| `website` | string or null | |
| `phone` | string or null | |
| `email` | string or null | |
| `industry` | string or null | |
| `employee_count` | integer or null | |
| `health_score` | integer or null | New Accounts start at 50. |
| `status_id` | string or null | Account status, such as `ras_active`. Read-only through the API. |
| `owner_id` | string or null | User ID of the Account's owner. See [GET /users](users-and-me.md). |
| `territory` | string or null | |
| `tier` | string or null | Read-only through the API. |
| `created_at` | string | ISO 8601 timestamp. |
| `updated_at` | string | ISO 8601 timestamp. |

Account status IDs: `ras_prospect`, `ras_active`, `ras_inactive`, `ras_churned`, `ras_suspended`.

```json
{
  "id": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
  "name": "Contoso Pharmaceuticals",
  "legal_name": "Contoso Pharmaceuticals Inc.",
  "website": "https://contoso.example",
  "phone": "+1 312 555 0142",
  "email": "accounts@contoso.example",
  "industry": "Healthcare",
  "employee_count": 250,
  "health_score": 72,
  "status_id": "ras_active",
  "owner_id": "5b8d1f3a-7e2c-4a9b-b6d4-1c3e5f7a9b20",
  "territory": "Midwest",
  "tier": null,
  "created_at": "2026-09-14T16:02:11.000Z",
  "updated_at": "2026-11-10T08:45:30.000Z"
}
```

---

## List Accounts

`GET /accounts` · Scope: `accounts:read`

Returns active Accounts, newest first. Deactivated Accounts aren't listed.

### Query parameters

| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `limit` | integer | No | 1 to 100. Default 20. |
| `cursor` | string | No | `meta.cursor` from the previous page. |

### Example

```bash
curl "https://crm.empiraa.app/api/v1/accounts?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
const res = await fetch("https://crm.empiraa.app/api/v1/accounts?limit=50", {
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const { data, meta } = await res.json();
```

### Response `200`

```json
{
  "data": [
    {
      "id": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
      "name": "Contoso Pharmaceuticals",
      "legal_name": null,
      "website": "https://contoso.example",
      "phone": null,
      "email": null,
      "industry": "Healthcare",
      "employee_count": 250,
      "health_score": 50,
      "status_id": null,
      "owner_id": null,
      "territory": null,
      "tier": null,
      "created_at": "2026-11-12T09:30:00.000Z",
      "updated_at": "2026-11-12T09:30:00.000Z"
    }
  ],
  "meta": {
    "cursor": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
    "total": 184,
    "hasMore": true
  },
  "error": null
}
```

`meta.total` is the number of Accounts in the workspace.

**Webhook events:** none.

---

## Create an Account

`POST /accounts` · Scope: `accounts:write`

### Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `name` | string | Yes | |
| `legal_name` | string or null | No | |
| `website` | string or null | No | |
| `phone` | string or null | No | |
| `email` | string or null | No | |
| `industry` | string or null | No | |
| `employee_count` | integer or null | No | |
| `territory` | string or null | No | |
| `owner_id` | string or null | No | A user ID from `GET /users`. |

### Example

```bash
curl -X POST https://crm.empiraa.app/api/v1/accounts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contoso Pharmaceuticals", "website": "https://contoso.example", "industry": "Healthcare"}'
```

```js
const res = await fetch("https://crm.empiraa.app/api/v1/accounts", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ name: "Contoso Pharmaceuticals", website: "https://contoso.example", industry: "Healthcare" }),
});
```

### Response `201`

The new [Account object](#the-account-object) in `data`.

### Errors

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

**Webhook events:** none.

---

## Get an Account

`GET /accounts/{id}` · Scope: `accounts:read`

### Path parameters

| Parameter | Type | Notes |
| --- | --- | --- |
| `id` | string | Account ID. |

### Example

```bash
curl https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
const res = await fetch(
  "https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
```

### Response `200`

The [Account object](#the-account-object) in `data`.

### Errors

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

---

## Update an Account

`PATCH /accounts/{id}` · Scope: `accounts:write`

Send only the fields you want to change.

### Request body

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | |
| `legal_name` | string or null | |
| `website` | string or null | |
| `phone` | string or null | |
| `email` | string or null | |
| `industry` | string or null | |
| `employee_count` | integer or null | |
| `territory` | string or null | |
| `owner_id` | string or null | A user ID from `GET /users`, or `null`. |
| `health_score` | integer or null | |

### Example

```bash
curl -X PATCH https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"health_score": 72, "territory": "Midwest"}'
```

```js
await fetch("https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10", {
  method: "PATCH",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ health_score: 72, territory: "Midwest" }),
});
```

### Response `200`

The updated [Account object](#the-account-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No Account with that ID in this workspace, or `owner_id` isn't an active member of the workspace. |

**Webhook events:** none.

---

## Deactivate an Account

`DELETE /accounts/{id}` · Scope: `accounts:write`

Marks the Account inactive. The Account and its history are kept, but it no longer appears in `GET /accounts`.

### Example

```bash
curl -X DELETE https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
await fetch("https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10", {
  method: "DELETE",
  headers: { Authorization: "Bearer YOUR_API_KEY" },
});
```

### Response `204`

No body.

### Errors

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

**Webhook events:** none.

---

## Account spend records

## The spend object

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string | UUID. |
| `account_id` | string | The Account it belongs to. |
| `description` | string | |
| `amount` | number | In `currency`, major units (for example `1250.5`). |
| `currency` | string | Three-letter ISO 4217 code. |
| `spend_date` | string | ISO 8601 timestamp. |
| `category` | string or null | |
| `reference` | string or null | Your own reference, such as an invoice number. |
| `source` | string or null | Where the record came from, such as the name of your system. |
| `notes` | string or null | |
| `created_at` | string | ISO 8601 timestamp. |
| `updated_at` | string | ISO 8601 timestamp. |

```json
{
  "id": "9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13",
  "account_id": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10",
  "description": "Q4 license renewal",
  "amount": 12500,
  "currency": "USD",
  "spend_date": "2026-10-01T00:00:00.000Z",
  "category": "Software",
  "reference": "INV-20931",
  "source": "Billing system",
  "notes": null,
  "created_at": "2026-11-12T09:30:00.000Z",
  "updated_at": "2026-11-12T09:30:00.000Z"
}
```

---

## List an Account's spend records

`GET /accounts/{id}/spends` · Scope: `accounts:read`

Newest first. Cursor-paginated; `meta` has `cursor` and `hasMore`.

### Path and query parameters

| Parameter | In | Type | Required | Notes |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | Account ID. |
| `limit` | query | integer | No | 1 to 100. Default 20. |
| `cursor` | query | string | No | `meta.cursor` from the previous page. |

### Example

```bash
curl https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
const res = await fetch(
  "https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
```

### Response `200`

```json
{
  "data": [ { "id": "9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13", "account_id": "3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10", "description": "Q4 license renewal", "amount": 12500, "currency": "USD", "spend_date": "2026-10-01T00:00:00.000Z", "category": "Software", "reference": "INV-20931", "source": "Billing system", "notes": null, "created_at": "2026-11-12T09:30:00.000Z", "updated_at": "2026-11-12T09:30:00.000Z" } ],
  "meta": { "cursor": null, "hasMore": false },
  "error": null
}
```

### Errors

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

---

## Add spend records

`POST /accounts/{id}/spends` · Scope: `accounts:write`

Send one spend object, or an array of up to 100 to add several at once.

### Request body

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `description` | string | Yes | |
| `amount` | number | Yes | |
| `spend_date` | string | Yes | ISO 8601 date or timestamp. |
| `currency` | string | No | Exactly three letters, such as `USD`. If left out, it's stored as `GBP`, so always send it. |
| `category` | string or null | No | |
| `reference` | string or null | No | |
| `source` | string or null | No | |
| `notes` | string or null | No | |

### Example: one record

```bash
curl -X POST https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Q4 license renewal", "amount": 12500, "currency": "USD", "spend_date": "2026-10-01", "reference": "INV-20931"}'
```

```js
await fetch("https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    description: "Q4 license renewal",
    amount: 12500,
    currency: "USD",
    spend_date: "2026-10-01",
    reference: "INV-20931",
  }),
});
```

Response `201`: the new [spend object](#the-spend-object) in `data`.

### Example: several records

```js
await fetch("https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends", {
  method: "POST",
  headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
  body: JSON.stringify([
    { description: "October order", amount: 4200, currency: "USD", spend_date: "2026-10-15" },
    { description: "November order", amount: 3900, currency: "USD", spend_date: "2026-11-03" },
  ]),
});
```

Response `201`: an array of spend objects in `data`, and the number created in `meta.count`.

```json
{
  "data": [ { "id": "1c3e5a7b-9d0f-4e2a-8b6c-4d2f0a8e6c11", "description": "October order", "amount": 4200, "currency": "USD" } ],
  "meta": { "cursor": null, "count": 2 },
  "error": null
}
```

(Shortened: each item in `data` is a full spend object.)

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | The array is empty or has more than 100 items; a required field is missing; `amount` isn't a number; `spend_date` isn't a date; `currency` isn't three letters; or an optional field isn't a string. In an array, `title` names the item, such as `items[3].amount is required and must be a number`. |
| 404 | `NOT_FOUND` | No Account with that ID in this workspace. |

---

## Get a spend record

`GET /accounts/{id}/spends/{spendId}` · Scope: `accounts:read`

### Path parameters

| Parameter | Type | Notes |
| --- | --- | --- |
| `id` | string | Account ID. |
| `spendId` | string | Spend record ID. |

### Example

```bash
curl https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends/9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
await fetch(
  "https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends/9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13",
  { headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
```

### Response `200`

The [spend object](#the-spend-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such Account, or the spend record doesn't belong to it. |

---

## Update a spend record

`PATCH /accounts/{id}/spends/{spendId}` · Scope: `accounts:write`

Send only the fields you want to change: `description` (string), `amount` (number), `currency` (three letters), `spend_date` (ISO 8601; can't be cleared), and `category`, `reference`, `source`, `notes` (string or `null`).

### Example

```bash
curl -X PATCH https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends/9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 11800, "notes": "Credit applied"}'
```

```js
await fetch(
  "https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends/9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13",
  {
    method: "PATCH",
    headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
    body: JSON.stringify({ amount: 11800, notes: "Credit applied" }),
  },
);
```

### Response `200`

The updated [spend object](#the-spend-object) in `data`.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | A field has the wrong type, or `currency` isn't three letters. |
| 404 | `NOT_FOUND` | No such Account, or the spend record doesn't belong to it. |

---

## Delete a spend record

`DELETE /accounts/{id}/spends/{spendId}` · Scope: `accounts:write`

Deletes the spend record permanently.

### Example

```bash
curl -X DELETE https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends/9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13 \
  -H "Authorization: Bearer YOUR_API_KEY"
```

```js
await fetch(
  "https://crm.empiraa.app/api/v1/accounts/3f6c2a1e-8b4d-4c2a-9f1e-2b7d5a9c4e10/spends/9a7e2c4b-1d3f-4b6a-8e0c-2f4a6b8d0e13",
  { method: "DELETE", headers: { Authorization: "Bearer YOUR_API_KEY" } },
);
```

### Response `204`

No body.

### Errors

| Status | Code | When |
| --- | --- | --- |
| 404 | `NOT_FOUND` | No such Account, or the spend record doesn't belong to it. |