Company structure
Company structure endpoints: parameters, fields and example responses.
Developer documentation
- GET
/api/v1/companies - GET
/api/v1/companies/{id} - GET
/api/v1/job-titles - GET
/api/v1/job-titles/{id} - GET
/api/v1/locations - GET
/api/v1/locations/{id} - GET
/api/v1/org-units - GET
/api/v1/org-units/{id}
Lists companies
GET /api/v1/companies
Scope: org:read
Companies inside the key's scope. The tax number is not returned. The order is by ID and stable; no total count is returned. Sample records are not listed.
Parameters
| Field | Type | Description |
|---|---|---|
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
name | stringrequired | Legal name of the company. |
city | stringrequirednullable | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"data": [
{
"id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"name": "Marmara Lojistik Ltd.",
"city": "Bursa",
"is_demo": false,
"created_at": "2026-01-05T08:00:00.000Z",
"updated_at": "2026-03-02T09:15:00.000Z"
}
],
"next_cursor": null
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Returns one company
GET /api/v1/companies/{id}
Scope: org:read
The tax number is not returned. A record the key cannot see and a record that does not exist get the same 404 response.
Parameters
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the company. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
name | stringrequired | Legal name of the company. |
city | stringrequirednullable | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"name": "Marmara Lojistik Ltd.",
"city": "Bursa",
"is_demo": false,
"created_at": "2026-01-05T08:00:00.000Z",
"updated_at": "2026-03-02T09:15:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Lists job titles
GET /api/v1/job-titles
Scope: org:read
Job titles belong to the account (they have no company): every key with the org:read scope sees all of them, even when it is bound to a company, location or unit, and every key with the employees:write scope can assign any title of the account. The order is by ID and stable; no total count is returned. Sample records are not listed.
Parameters
| Field | Type | Description |
|---|---|---|
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
title | stringrequired | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"data": [
{
"id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"title": "Vardiya Amiri",
"is_demo": false,
"created_at": "2026-01-05T08:12:00.000Z",
"updated_at": "2026-01-05T08:12:00.000Z"
}
],
"next_cursor": null
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Returns one job title
GET /api/v1/job-titles/{id}
Scope: org:read
A record that does not exist gets the 404 response.
Parameters
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the job title. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
title | stringrequired | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"id": "9e7d6c5b-4a39-4821-8f70-6e5d4c3b2a19",
"title": "Vardiya Amiri",
"is_demo": false,
"created_at": "2026-01-05T08:12:00.000Z",
"updated_at": "2026-01-05T08:12:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Lists locations
GET /api/v1/locations
Scope: org:read
Locations inside the key's scope. The order is by ID and stable; no total count is returned. Sample records are not listed.
Parameters
| Field | Type | Description |
|---|---|---|
company_ (query) | string (uuid) | Only locations of this company. |
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
name | stringrequired | |
city | stringrequirednullable | |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"data": [
{
"id": "5d2f0a77-3c1b-4f58-8a0e-6b9d4c2e7f31",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"name": "Bursa Depo",
"city": "Bursa",
"created_at": "2026-01-05T08:05:00.000Z",
"updated_at": "2026-01-05T08:05:00.000Z"
}
],
"next_cursor": null
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Returns one location
GET /api/v1/locations/{id}
Scope: org:read
A record the key cannot see and a record that does not exist get the same 404 response.
Parameters
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the location. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
name | stringrequired | |
city | stringrequirednullable | |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"id": "5d2f0a77-3c1b-4f58-8a0e-6b9d4c2e7f31",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"name": "Bursa Depo",
"city": "Bursa",
"created_at": "2026-01-05T08:05:00.000Z",
"updated_at": "2026-01-05T08:05:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Lists organisation units
GET /api/v1/org-units
Scope: org:read
Units inside the key's scope; the tree is built from parent_id. The order is by ID and stable; no total count is returned. Sample records are not listed.
Parameters
| Field | Type | Description |
|---|---|---|
company_ (query) | string (uuid) | Only units of this company. |
cursor (query) | string | The next_cursor value of the previous response. It is opaque; send it with the same key and the same filter. |
limit (query) | integer | Page size; a value above the maximum is lowered to the maximum. |
Responses
200 Successful
A list response comes in the { data, next_cursor } envelope.
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
parent_ | string (uuid)requirednullable | Parent unit; null at the root. |
location_ | string (uuid)requirednullable | Location of the unit; null when there is none. |
kind | stringrequired | Values: department, unit |
name | stringrequired | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"data": [
{
"id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"parent_id": null,
"location_id": "5d2f0a77-3c1b-4f58-8a0e-6b9d4c2e7f31",
"kind": "department",
"name": "Operasyon",
"is_demo": false,
"created_at": "2026-01-05T08:10:00.000Z",
"updated_at": "2026-02-11T13:40:00.000Z"
}
],
"next_cursor": null
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout
Returns one organisation unit
GET /api/v1/org-units/{id}
Scope: org:read
A record the key cannot see and a record that does not exist get the same 404 response.
Parameters
| Field | Type | Description |
|---|---|---|
id (path) | string (uuid)required | ID of the unit. |
Responses
200 Successful
| Field | Type | Description |
|---|---|---|
id | string (uuid)required | |
company_ | string (uuid)required | |
parent_ | string (uuid)requirednullable | Parent unit; null at the root. |
location_ | string (uuid)requirednullable | Location of the unit; null when there is none. |
kind | stringrequired | Values: department, unit |
name | stringrequired | |
is_ | booleanrequired | A record that came with the sample data. List endpoints do not return sample records; a single-record read returns them with this field set to true. |
created_ | string (date-time)required | |
updated_ | string (date-time)required | The moment the record's own fields last changed (UTC). |
Example response
{
"id": "c4a1e2b3-7d6f-4e5a-9b8c-1f2e3d4c5b6a",
"company_id": "0b8f6c1e-5f0a-4c7e-9a43-2f6f3a1d9c10",
"parent_id": null,
"location_id": "5d2f0a77-3c1b-4f58-8a0e-6b9d4c2e7f31",
"kind": "department",
"name": "Operasyon",
"is_demo": false,
"created_at": "2026-01-05T08:10:00.000Z",
"updated_at": "2026-02-11T13:40:00.000Z"
}Error codes
400:bad_request,validation_failed,key_in_query,cookie_with_key,idempotency_key_required,idempotency_key_invalid,cursor_invalid401:unauthorized403:insufficient_scope,forbidden,module_disabled,trial_ended,key_suspended404:not_found429:rate_limited500:internal_error503:timeout