---
title: Accounts
description: Companies and organisations you sell to. An account owns its contact relations, opportunities and activities.
canonical: https://developers.coevera.com/reference/rest/accounts/
section: rest
verification: schema
generatedFrom: spec 5e43371 (2026-10-16)
publisher: Coevera
---

# Accounts

Companies and organisations you sell to. An account owns its contact relations, opportunities and activities.

Each account has an owner (a Client, the API's name for a user) and a sales unit, which decide who can see it. Contacts are linked to accounts through ContactAccountRelations. Accounts and contacts are the two entities that can be merged.

Family: Accounts. GraphQL: [account](https://developers.coevera.com/reference/graphql/account.md). Base URL: `https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}`.

| Method | Path | Operation |
| --- | --- | --- |
| GET | `/entities/Accounts` | List accounts |
| POST | `/entities/Accounts` | Create an account |
| GET | `/entities/Accounts/{id}` | Get an account |
| PATCH | `/entities/Accounts/{id}` | Update an account |
| DELETE | `/entities/Accounts/{id}` | Delete an account |
| POST | `/entities/Accounts/batch-modify` | Create or update accounts in a batch |
| POST | `/entities/Accounts/batch-delete` | Delete accounts in a batch |
| POST | `/entities/Accounts/batch-restore` | Restore deleted accounts |
| POST | `/entities/Accounts/merge` | Merge accounts |

## List accounts

`GET /entities/Accounts`

Returns the accounts the API application can read, one page at a time. In the list envelope, `total` counts every match; page forward with `after` set to `page_info.end_cursor` until `has_next_page` is false.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `include-deleted` | query | boolean | Include soft-deleted records. Lists only; get-by-id refuses it. |
| `first` | query | integer | Page size. Default 30, maximum 100; a larger value is refused with HTTP 400, code 117. (default 30, 1 to 100) |
| `last` | query | integer | Return the last N records of the result; together with `first`, the last N of the first M. Maximum 100. (1 to 100) |
| `before` | query | string | Cursor from `page_info.start_cursor`, to page backwards. URL-encode it. |
| `after` | query | string | Cursor from `page_info.end_cursor` of the previous page. URL-encode it: cursors are base64, and a raw + becomes a space. |
| `expand` | query | string | Related records to return inline instead of their URIs, comma-separated; dots reach nested relations, as in `account_relations.account`. |
| `order-by` | query | string | Fields to sort by, comma-separated. A leading - sorts descending, as in `-modified`; dotted paths sort by related fields. |
| `filter` | query | object | `filter[field]=value`. Separate several values with a raw comma (OR), as in `filter[name]=north,south`. Encode a comma that belongs to a value as %2C. URLSearchParams and Python requests encode every comma, so build the filter part of the query string yourself. Dotted paths filter on related records, as in `filter[owner.email]`. Encode a + in a value as %2B: query values are form-decoded, so a raw + becomes a space. |
| `filter-op` | query | object | `filter-op[field]=operator`, one per field: eq (the default), ieq, not-eq, not-ieq, contains, icontains, starts, istarts, ends, iends, gt, gte, lt, lte, between, null, not-null, empty and not-empty. null, not-null, empty and not-empty take no filter value; gt, gte, lt and lte take exactly one. |
| `load-only` | query | string | Fields to return, comma-separated (raw or encoded commas both work here); dots select nested fields, as in `owner.id`. All fields are returned without it. Lists only: get-by-id refuses it with HTTP 400, code 118. |

Responses: 200 (Page of Account records.: `success`, `total`, `page_info`, `data`), 400, 401, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts?first=10&filter%5Bname%5D=north&filter-op%5Bname%5D=icontains' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Create an account

`POST /entities/Accounts`

Creates one account and answers 201 with the record. `name` and `owner_id` are required; relations are set by id (`owner_id`, `unit_id`, `account_type_id`).

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |

Request body: The new record's fields. Relations are set by id. Schema `createAccountInput`. Required: `name`, `owner_id`.

Responses: 201 (The created Account record.: `success`, `data`), 400, 401, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Northwind Analytics",
  "owner_id": "37000000-0000-4000-a000-000000000001",
  "email1": "northwind@example.com",
  "phone1": "+1 555 0100",
  "city": "Seattle",
  "country": "United States"
}'
```

## Get an account

`GET /entities/Accounts/{id}`

Returns one account by id. `expand` returns related records inline instead of their URIs.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Account record to retrieve. |
| `expand` | query | string | Related records to return inline instead of their URIs, comma-separated; dots reach nested relations. The only parameter this call accepts. |

Responses: 200 (The Account record.: `success`, `data`), 400, 401, 404, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts/1d000000-0000-4000-a000-000000000001?expand=owner' \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Update an account

`PATCH /entities/Accounts/{id}`

Changes the fields you send and leaves the rest as they are; there is no PUT. An `id` in the body that differs from the one in the URL is refused with code 2002.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Account record to update. |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |

Request body: The fields to change. Schema `updateAccountInput`.

Responses: 200 (The changed Account record.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts/1d000000-0000-4000-a000-000000000001' \
  --request PATCH \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "phone1": "+1 555 0199"
}'
```

## Delete an account

`DELETE /entities/Accounts/{id}`

Soft-deletes one account and answers with its id. A deleted account can be brought back with batch-restore.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `id` | path | string (uuid) | Required. Id of the Account record to delete. |

Responses: 200 (Deletion confirmation.: `success`, `data`), 400, 401, 404, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts/1d000000-0000-4000-a000-000000000001' \
  --request DELETE \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET"
```

## Create or update accounts in a batch

`POST /entities/Accounts/batch-modify`

An item with an `id` updates that account; an item without one creates an account. By default one invalid item fails the whole call with HTTP 422 and nothing is written; with `rollback-method=1` the valid items are written and the response has an id or an error for each item, in input order.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `validation-level` | query | integer | Bit mask that relaxes validation on this write. 0 (the default) validates everything. Bits: 2 skip unchanged fields, 4 skip admin-defined validations, 8 allow read-only fields, 16 skip relation checks, 32 skip value checks, 64 skip invalid recalculations, 128 skip step-checklist gates, 256 add conditional field requirements, 512 skip uniqueness checks. Add bits together (20 = 4 + 16); member names and comma lists such as 4,16 work too. A value with an internal-only bit is refused with HTTP 400, code 117. |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of records: an item with an `id` updates, an item without one creates. Schema `batchAccountInput`. Required: `name`, `owner_id`.

Responses: 200 (Result per item, in request order: the id of the created or updated record, or the error.: `success`, `data`), 400, 401, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts/batch-modify' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "name": "Northwind account",
    "owner_id": "37000000-0000-4000-a000-000000000001"
  },
  {
    "id": "1d000000-0000-4000-a000-000000000001",
    "phone1": "+1 555 0199"
  }
]'
```

## Delete accounts in a batch

`POST /entities/Accounts/batch-delete`

Soft-deletes the accounts whose ids are in the body, a JSON array. By default an unknown id fails the whole call with HTTP 404.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of ids.

Responses: 200 (Result per id, in request order: the id of the deleted record, or the error.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts/batch-delete' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  "1d000000-0000-4000-a000-000000000001",
  "1d000000-0000-4000-a000-000000000002"
]'
```

## Restore deleted accounts

`POST /entities/Accounts/batch-restore`

Restores the soft-deleted accounts whose ids are in the body, a JSON array.

| Parameter | In | Type | Description |
| --- | --- | --- | --- |
| `rollback-method` | query | integer | 0, the default: one failed item fails the whole batch (HTTP 422, or 404 for an unknown id) and nothing is written. 1: the valid items are written and the call answers 200 with success false and one result per item, an id or an error, in input order. Check every item. (default 0) |

Request body: A JSON array of ids.

Responses: 200 (Result per id, in request order: the id of the restored record, or the error.: `success`, `data`), 400, 401, 404, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts/batch-restore' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '[
  "1d000000-0000-4000-a000-000000000001",
  "1d000000-0000-4000-a000-000000000002"
]'
```

## Merge accounts

`POST /entities/Accounts/merge`

Merges duplicates into one account. `master` is the account to keep, with any field values to keep; the accounts in `secondary_ids` are merged into it and their relations move to it.

Request body: `master`, the record to keep with any field values to keep, and `secondary_ids`, the duplicates to merge into it. Schema `batchAccountInput`.

Responses: 200 (The merged master record.: `success`, `data`), 400, 401, 422, 429, 500.

```bash
curl 'https://{region}.api.coevera.com/api/v100/rest/spaces/{space_id}/entities/Accounts/merge' \
  --request POST \
  --user "$COEVERA_API_KEY:$COEVERA_API_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{
  "master": {
    "id": "1d000000-0000-4000-a000-000000000001"
  },
  "secondary_ids": [
    "1d000000-0000-4000-a000-000000000002"
  ]
}'
```

## Account fields

| Field | Type | Notes |
| --- | --- | --- |
| `id` | uuid | Read-only. Unique identifier of entity. |
| `name` | string | Required on create. Name of the entity and its default text representation. |
| `owner_id` | uuid → Clients | Required on create. Id of the account owner. |
| `created` | date-time | Creation time. |
| `picture` | uri → CloudObjects | Profile picture or company logo associated with the account. |
| `account_class` | integer | Manual classification grade assigned to the account. Values: 1 NoClass, 2 ClassA, 3 ClassB, 4 ClassC, 5 ClassD. |
| `account_type_id` | uuid → AccountTypes | Id of the account type assigned to this account. |
| `address` | string | Street address of the account. |
| `city` | string | City of the account address. |
| `comments` | string | Free-form notes describing the account. |
| `country` | string | Country of the account address. |
| `currency_exchange_rates_list_id` | uuid → CurrencyExchangeRatesLists | Id of the currency exchange rate list applied to this account. |
| `customer_type_id` | uuid → Data | Id of the customer type (e.g. |
| `email1` | string | Primary email address of the account. |
| `email2` | string | Additional email address. |
| `email3` | string | Additional email address. |
| `email4` | string | Additional email address. |
| `email5` | string | Additional email address. |
| `home_page` | string | Website URL of the account. |
| `industry_id` | uuid → Data | Id of the industry classification. |
| `is_archived` | boolean | True when the account has been archived. |
| `last_ai_account_hierarchy_applied` | date-time | Time when an AI-suggested account hierarchy was last applied to this account. |
| `last_ai_org_chart_applied` | date-time | Time when an AI-suggested org chart was last applied to this account. |
| `parent_account_id` | uuid → Accounts | Id of the parent account in the corporate hierarchy. |
| `parent_account_relation_type_id` | uuid → ParentAccountRelationTypes | Id of the parent-account relationship type. |
| `phone1` | string | Primary phone number of the account. |
| `phone2` | string | Additional phone number. |
| `phone3` | string | Additional phone number. |
| `phone4` | string | Additional phone number. |
| `phone5` | string | Additional phone number. |
| `picture_id` | uuid → CloudObjects | Id of the profile picture document. |
| `quick_parent_account_name` | string | Free-text parent-account name used when the parent has not been linked to an actual Account record. |
| `share_mode` | integer | Sharing model applied on top of the owner/unit visibility (e.g. Values: 0 Standard, 1 Private, 2 AllView, 3 AllEdit. |
| `state_province` | string | State or province of the account address. |
| `unit_id` | uuid → SalesUnits | Id of the sales unit. |
| `zip_code` | string | ZIP or postal code of the account address. |
| `revision` | integer | Revision when entity was lastly changed. |
| `social_media` | uri → AccountSocialRelations | Social network profiles linked to this account (e.g. |
| `sharing_units` | array of uri → AccountSharingSalesUnitRelations | Sales units that have been granted shared access to this account. |
| `sharing_clients` | array of uri → AccountSharingClientRelations | Users that have been granted shared access to this account. |
| `documents` | array of uri → CloudObjectRelations | Documents linked to this account. |
| `is_unsubscribed` | boolean | If account has any unsubscribed email. |
| `tags` | array of uri → TagRelations | Tag labels applied to this account. |
| `static_profiles` | array of uri → ProfileRelations | Saved view profiles this account currently matches. |
| `is_delete_protected` | boolean | Read-only. True when the record is protected against deletion because it must always exist in the space. |
| `is_deleted` | boolean | Read-only. Specifies if the entity is considered deleted. |
| `modified` | date-time | Read-only. Last modification time. |
| `account_type` | uri → AccountTypes | Read-only. Account type that classifies this account. |
| `currency_exchange_rates_list` | uri → CurrencyExchangeRatesLists | Read-only. Currency exchange rate list used to convert monetary fields linked to this account. |
| `customer_type` | uri → Data | Read-only. Customer category (e.g. |
| `industry` | uri → Data | Read-only. Industry the account operates in. |
| `owner` | uri → Clients | Read-only. Sales user who owns this account. |
| `parent_account` | uri → Accounts | Read-only. Parent account in a corporate hierarchy. |
| `parent_account_relation_type` | uri → ParentAccountRelationTypes | Read-only. Type of relationship to the parent account (e.g. |
| `unit` | uri → SalesUnits | Read-only. Sales unit this account is assigned to. |
| `health_category` | uuid | Read-only. Coarser bucket of health_status used for grouping and reporting. |
| `health_status` | integer | Read-only. Computed entity-health state (e.g. |
| `formatted_name` | string | Read-only. Display version of the account name, used in lists and references. |
| `is_favorite` | boolean | Read-only. True when the current authenticated user has marked this account as favorite. |
| `health` | object | Read-only. Composite entity-health summary, combining current and previous state with last-calculation metadata. |
| `modified_by_user` | date-time | Read-only. Timestamp of the most recent modification made by an end user (excluding system changes). |

Custom fields appear in your space's live spec: `GET /api/v100/rest/spaces/{space_id}/openapi.json` with your credentials.

## Errors

Every error body has `success: false`, `http_status`, `code`, `name` and `message`. Branch on `code`: the status alone does not tell a missing permission from a bad parameter.

| HTTP | When |
| --- | --- |
| 400 | Bad request: a bad or unknown parameter (codes 117, 118), a missing permission (code 50), conflicting data (code 2002) or any other API error. The REST API answers 400 where others answer 403 or 409; check `code`. |
| 401 | Not authenticated: missing or wrong credentials, a credential of another space, or an expired token (code 401, ERROR_UNAUTHORIZED). |
| 404 | No such record or entity (code 143 ERROR_NO_ENTITY, or 2006 ERROR_UNKNOWN_TYPE). |
| 422 | Validation failed (code 40000, with the failing fields) or a required parameter is missing (code 119). By default one failed item fails a whole batch and nothing is written. |
| 429 | Too many requests (code 182). Wait for the seconds in Retry-After, then retry. |
| 500 | Unexpected server error (code 1000, ERROR_UNKNOWN). |

All error codes: https://developers.coevera.com/reference/errors.md; how to handle them: https://developers.coevera.com/concepts/errors.md

## Webhook events for accounts

`Account.Create`, `Account.Delete`, `Account.DocumentLinked`, `Account.OwnerChanged`, `Account.Update`. Payloads: https://developers.coevera.com/webhooks/events.md

Subscribe with [Create a webhook](https://developers.coevera.com/reference/rest/webhooks.md).