Customers API

REST API reference for managing customers and sites programmatically in octoja.

Written By Erdinc Akay

Last updated 26 days ago

The Customers API lets you query and manage customer records and their sites.

For the complete, always-current list of endpoints, parameters, and response fields for the version you are running, use the interactive OpenAPI (Swagger) interface at https://<your-octoja-instance>/openapi/index.html.

Endpoints

All requests must be authenticated as a logged-in user. The required permission is listed per endpoint below; these custom permission policies are not reflected in the Swagger schema.

Operation	Endpoint	Notes
List	`GET /api/customers`	Authenticated user. Optional `search` filters by customer name, external reference, or tag.
Get	`GET /api/customers/{id}`	Authenticated user.
Create	`POST /api/customers`	`customers.manage`. Required: `name`. `externalReference` is optional (your own PSA or billing reference).
Update	`POST /api/customers/{id}`	`customers.manage`. Uses the `UpdateValue<T>` envelope — see below.
Delete	`DELETE /api/customers/{id}`	`customers.manage`. Soft delete — see below.

Update a customer

Updates use the UpdateValue<T> envelope. Each scalar field you want to change must be wrapped as { "hasValue": true, "value": ... }. Omit the field (or send { "hasValue": false }) to leave it unchanged. For nullable fields, set "value": null inside the envelope to clear the current value.

The sites field uses an UpdateList<T> envelope — a list of add / update / remove operations rather than a replacement array.

Example body that renames the customer, clears the external reference, and replaces the tag list:

{  "newName":              { "hasValue": true, "value": "Acme GmbH" },  "newExternalReference": { "hasValue": true, "value": null },  "tags":                 { "hasValue": true, "value": ["vip", "managed"] }}

Fields worth knowing (the full list and types are in Swagger):

newExternalReference, address, and contact are nullable — send "value": null inside the envelope to clear them.
tags replaces the whole list when sent; omit the field to leave tags unchanged. See Tag validation below.
sites is an operation list, not a replacement array. See Managing sites below.

Tag validation

When tags is sent, octoja first drops empty/whitespace entries and deduplicates the array, then validates the result before saving. The endpoint returns 400 Bad Request if more than 50 tags remain, or if any single tag exceeds 100 characters.

Managing sites

The sites field accepts a list of operations. Each entry is shaped as { "op": "Add" | "Update" | "Remove", "id": <siteId or null>, "values": { "name": { "hasValue": true, "value": "..." } } }. The name property inside values is itself an UpdateValue<string> envelope.

Add — requires values.name; id is omitted or null.
Update — requires id (the existing siteId) and values.name; renames the site.
Remove — requires id; values may be omitted.

Example body that adds one site, renames another, and removes a third:

{  "sites": {    "hasValue": true,    "value": [      { "op": "Add",    "values": { "name": { "hasValue": true, "value": "Berlin office" } } },      { "op": "Update", "id": "1c2e...", "values": { "name": { "hasValue": true, "value": "Munich HQ" } } },      { "op": "Remove", "id": "9af3..." }    ]  }}

Delete a customer

Returns 400 Bad Request if any agent is still assigned to the customer — regardless of whether the agent is online, offline, or otherwise inactive. Reassign or remove those devices first.

Deleting a customer is a soft delete. The customer is marked as deleted and no longer appears in normal API results. Related records are retained.

Customer object