Skip to content

Company structure

Company structure endpoints: parameters, fields and example responses.

Developer documentation

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

companies.list: Parameters
FieldTypeDescription
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

companies.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
namestringrequiredLegal name of the company.
citystringrequirednullable
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

companies.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the company.

Responses

200 Successful

companies.get: Responses
FieldTypeDescription
idstring (uuid)required
namestringrequiredLegal name of the company.
citystringrequirednullable
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

job_titles.list: Parameters
FieldTypeDescription
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

job_titles.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
titlestringrequired
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

job_titles.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the job title.

Responses

200 Successful

job_titles.get: Responses
FieldTypeDescription
idstring (uuid)required
titlestringrequired
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

locations.list: Parameters
FieldTypeDescription
company_id (query)string (uuid)Only locations of this company.
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

locations.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
namestringrequired
citystringrequirednullable
created_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

locations.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the location.

Responses

200 Successful

locations.get: Responses
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
namestringrequired
citystringrequirednullable
created_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

org_units.list: Parameters
FieldTypeDescription
company_id (query)string (uuid)Only units of this company.
cursor (query)stringThe next_cursor value of the previous response. It is opaque; send it with the same key and the same filter.
limit (query)integerPage size; a value above the maximum is lowered to the maximum.

Responses

200 Successful

A list response comes in the { data, next_cursor } envelope.

org_units.list: Each item in the list (data[])
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
parent_idstring (uuid)requirednullableParent unit; null at the root.
location_idstring (uuid)requirednullableLocation of the unit; null when there is none.
kindstringrequired Values: department, unit
namestringrequired
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: 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

org_units.get: Parameters
FieldTypeDescription
id (path)string (uuid)requiredID of the unit.

Responses

200 Successful

org_units.get: Responses
FieldTypeDescription
idstring (uuid)required
company_idstring (uuid)required
parent_idstring (uuid)requirednullableParent unit; null at the root.
location_idstring (uuid)requirednullableLocation of the unit; null when there is none.
kindstringrequired Values: department, unit
namestringrequired
is_demobooleanrequiredA 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_atstring (date-time)required
updated_atstring (date-time)requiredThe 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_invalid
  • 401: unauthorized
  • 403: insufficient_scope, forbidden, module_disabled, trial_ended, key_suspended
  • 404: not_found
  • 429: rate_limited
  • 500: internal_error
  • 503: timeout