Companies
The organizations behind your contacts — the Company object and every endpoint for listing, creating, updating and deleting companies.
A company is an organization a project works with. Contacts belong to a company through their company_uuid, so
several people can sit under one customer. A company has contact details of its own (website, address, tax_id)
and can be assigned to a project member.
Deleting a company is permanent. Its contacts stay and lose their company_uuid.
Field types follow the field notation.
Access
Companies are part of the customer base and use the clients scope and permissions: every endpoint on this page
requires the projects and clients OAuth scopes. The user must be a member of the project, and the owner's
subscription must be active. Otherwise the endpoint returns 404 RES_NOT_FOUND. The project owner bypasses permission
checks.
| Permission | Grants |
|---|---|
can_view_own_clients |
Read companies assigned to the user (user_uuid) |
can_view_role_clients |
Read companies assigned to members with the same role as the user |
can_view_all_clients |
Read every company in the project |
can_edit_clients |
Create, update and delete companies |
Every endpoint that addresses a company sees only the companies within the user's widest view permission. A company
outside that range behaves as if it does not exist (404 RES_NOT_FOUND).
user_uuid must be a member of the project; otherwise the request fails with 400 RES_NOT_FOUND. On update it is
checked only when it changes.
Company Object
Company Structure
| Field | Type | Description |
|---|---|---|
| uuid | uuid | Company ID |
| name | string | Name, 1–255 characters |
| website | string | Website, up to 255 characters. May be empty |
| address | string | Address, up to 512 characters |
| tax_id | string | Tax or registration number, up to 32 characters. May be empty |
| note | string | Free-text note, up to 1024 characters |
| user_uuid | ?uuid | Project member responsible for the company |
| user_name | string | The responsible member's full name |
| user_email | ?string | The responsible member's email |
| contacts_count | integer | Number of contacts in the company |
| orders_count | integer | Number of non-deleted orders of the company's contacts. Only in List Companies |
| created_at | ISO8601 datetime | When the company was created |
| updated_at | ISO8601 datetime | When the company was last changed |
contacts_count and orders_count are computed by Postgres and are returned as strings, e.g. "3".
Example Company
{
"uuid": "0199a5b1-3c4d-7e5f-8061-728394a5b6c7",
"name": "Acme Windows",
"website": "acme.example",
"address": "12 Industrial Rd, Springfield",
"tax_id": "7701234567",
"note": "",
"user_uuid": "0198e7aa-91f0-7c22-a4d1-0f9e8d7c6b5a",
"user_name": "Anna Petrova",
"user_email": "[email protected]",
"contacts_count": "3",
"orders_count": "7",
"created_at": "2026-10-06T09:12:00.000Z",
"updated_at": "2026-10-06T09:12:00.000Z"
}List Companies
GET /api/v1/projects/{project.uuid}/companies
Returns the companies visible to the user, sorted by name.
Requires one of can_view_own_clients, can_view_role_clients, can_view_all_clients.
Query String Params
| Field | Type | Description |
|---|---|---|
| page? | integer | Page number, from 1. Default 1 |
| limit? | integer | Page size, 1–100. Default 50 |
| filters? | string | A URL-encoded JSON array of filter objects, see below. Invalid JSON is ignored |
Each filter is {"field", "operator", "value"}. Filters on different fields combine with AND.
field |
value |
Matches |
|---|---|---|
name, website, tax_id, address, note |
string | The column. operator is include (default, case-insensitive), equal or starts_with |
member |
uuid | Responsible member |
contacts_count, orders_count |
number | The counts above. operator is equal, greater or less |
Response
200 OK — an array of company objects.
Errors
| Status | Code | When |
|---|---|---|
| 403 | AUTH_INSUFFICIENT_SCOPE |
The token lacks projects or clients |
| 403 | AUTH_NO_PROJECT_ACCESS |
The user's role has no contact view permission |
| 404 | RES_NOT_FOUND |
The project does not exist or is not accessible |
To list the contacts of a company, filter List Contacts by company_uuid.
Get Company
GET /api/v1/projects/{project.uuid}/companies/{company.uuid}
Returns a single company.
Requires one of can_view_own_clients, can_view_role_clients, can_view_all_clients.
Errors
| Status | Code | When |
|---|---|---|
| 403 | AUTH_INSUFFICIENT_SCOPE |
The token lacks projects or clients |
| 403 | AUTH_NO_PROJECT_ACCESS |
The user's role has no contact view permission |
| 404 | RES_NOT_FOUND |
The project or company does not exist, or the company is outside the user's visibility |
Create Company
POST /api/v1/projects/{project.uuid}/companies
Creates a company.
Requires can_edit_clients.
JSON Params
| Field | Type | Description |
|---|---|---|
| name | string | 1–255 characters, trimmed |
| website? | string | Up to 255 characters |
| address? | string | Up to 512 characters |
| tax_id? | string | Up to 32 characters |
| note? | string | Up to 1024 characters |
| user_uuid? | ?uuid | Responsible member. Default: the authenticated user; null leaves it unassigned |
Example Request
{
"name": "Acme Windows",
"website": "acme.example",
"tax_id": "7701234567"
}Response
201 Created
{
"uuid": "0199a5b1-3c4d-7e5f-8061-728394a5b6c7"
}Errors
| Status | Code | When |
|---|---|---|
| 400 | REQ_VALIDATION_FAILED |
The body does not match the schema |
| 400 | RES_NOT_FOUND |
user_uuid is not a member of the project |
| 403 | AUTH_INSUFFICIENT_SCOPE |
The token lacks projects or clients |
| 403 | AUTH_NO_PROJECT_ACCESS |
The user's role lacks can_edit_clients |
| 404 | RES_NOT_FOUND |
The project does not exist or is not accessible |
Modify Company
PATCH /api/v1/projects/{project.uuid}/companies/{company.uuid}
Updates only the fields you send. Takes the same fields as Create Company, all optional, but at least one must be present.
Requires can_edit_clients.
Example Request
{
"website": "acme.example/en"
}Response
204 No Content
Errors
| Status | Code | When |
|---|---|---|
| 400 | REQ_VALIDATION_FAILED |
The body does not match the schema |
| 400 | REQ_NO_DATA_PROVIDED |
The body has no fields |
| 400 | RES_NOT_FOUND |
user_uuid is not a member of the project |
| 403 | AUTH_INSUFFICIENT_SCOPE |
The token lacks projects or clients |
| 403 | AUTH_NO_PROJECT_ACCESS |
The user's role lacks can_edit_clients |
| 404 | RES_NOT_FOUND |
The project or company does not exist, or is outside the user's visibility |
Replace Company
PUT /api/v1/projects/{project.uuid}/companies/{company.uuid}
Replaces the company. Every field of Create Company except user_uuid is required; user_uuid is
kept when omitted. Returns 204 No Content, with the same errors as Modify Company.
Delete Company
DELETE /api/v1/projects/{project.uuid}/companies/{company.uuid}
Deletes the company permanently. Its contacts stay and lose their company_uuid. A company that is the supplier of a
warehouse receipt cannot be deleted.
Requires can_edit_clients.
Response
204 No Content
Errors
| Status | Code | When |
|---|---|---|
| 403 | AUTH_INSUFFICIENT_SCOPE |
The token lacks projects or clients |
| 403 | AUTH_NO_PROJECT_ACCESS |
The user's role lacks can_edit_clients |
| 404 | RES_NOT_FOUND |
The project or company does not exist, or is outside the user's visibility |