Accounts

Create, read, update and deactivate Accounts, and record what each Account spends.

View as Markdown Open in Claude Open in ChatGPT

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.
`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#

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

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#

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"}'

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 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#

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

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 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#

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"}'

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 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#

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

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#

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

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#

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"}'

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 in data.

Example: several records#

JavaScript

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#

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"

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 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#

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"}'

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 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#

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"

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.

Accounts

The Account object#

List Accounts#

Query parameters#

Example#

Response 200#

Create an Account#

Request body#

Example#

Response 201#

Errors#

Get an Account#

Path parameters#

Example#

Response 200#

Errors#

Update an Account#

Request body#

Example#

Response 200#

Errors#

Deactivate an Account#

Example#

Response 204#

Errors#

Account spend records#

The spend object#

List an Account's spend records#

Path and query parameters#

Example#

Response 200#

Errors#

Add spend records#

Request body#

Example: one record#

Example: several records#

Errors#

Get a spend record#

Path parameters#

Example#

Response 200#

Errors#

Update a spend record#

Example#

Response 200#

Errors#

Delete a spend record#

Example#

Response 204#

Errors#

Response `200`#

Response `201`#

Response `200`#

Response `200`#

Response `204`#

Response `200`#

Response `200`#

Response `200`#

Response `204`#