P4 Software
/
activoHQ English
This page assumes the X-Api-Key header and the ?companyId= parameter described in the REST API for developers overview.
Every catalog endpoint follows the same shape. Use them to resolve ids before creating or updating Assets.
curl -s "https://acme.activohq.cloud/api/v1/Locations?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "X-Api-Key: $ACTIVOHQ_API_KEY"
Available catalog routes:
| Route | Returns |
|---|---|
GET /api/v1/Companies |
Companies |
GET /api/v1/Locations |
Locations |
GET /api/v1/cost-centers |
Cost centers |
GET /api/v1/depreciation-books |
Depreciation books |
GET /api/v1/Custodians |
Custodians |
GET /api/v1/Employees |
Employees (includes email) |
Each item in items[] has at least id, code and name. Employees also include email, and Locations also include rfidEpc (the location's RFID tag, if it has one). The Companies listed are only the active ones.
Asset models: the Assets' classifier is the asset model, which for now has no catalog endpoint of its own. Get its id from the
model.idfield of any asset returned byGET /api/v1/Assets, or from the application. The old asset categories were retired from the product and from the API.
The Locations, Cost centers, Depreciation books, Custodians and Employees catalogs also accept POST (create) and PUT (update). The same X-Api-Key header and ?companyId= parameter are required.
| Rule | Detail |
|---|---|
| POST success | 201 Created -- the Location header points at the new resource; the body carries {id, code, name} (Employees also include email). |
| PUT success | 200 OK -- the body carries the updated {id, code, name}. The PUT route appends /{id}, for example PUT /api/v1/Locations/{id}. |
| Duplicate code | 400 Bad Request -- {"error":"Code 'HQ-01' already exists."} (the message includes the code you sent). |
| Unknown id on PUT | 404 Not Found. |
| Required fields | code and name on every resource (if missing: Code is required. or Name is required.). |
isActive omitted |
If you do not send isActive, the record is saved as inactive (false). Always send isActive: true for active records. |
| PUT | Replaces the whole record: optional fields you do not send are saved blank. Send every field. |
curl -s -X POST "https://acme.activohq.cloud/api/v1/Locations?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "X-Api-Key: $ACTIVOHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "HQ-01",
"name": "Head Office",
"city": "Panama City",
"country": "PA",
"isActive": true
}'
Response (201 Created):
{ "id": "d1a2b3c4-e5f6-7890-abcd-ef1234567890", "code": "HQ-01", "name": "Head Office" }
| Field | Type | Required | Notes |
|---|---|---|---|
code |
string | Yes | Unique within the company. |
name |
string | Yes | Display name. |
description |
string | No | Free-text description. |
address1 |
string | No | Street address. |
city |
string | No | City. |
stateProvince |
string | No | State or province. |
country |
string | No | Country (ISO 3166-1 alpha-2 recommended, for example "PA"). |
isActive |
boolean | No | If omitted it is saved as false (inactive); send true for an active record. |
| Field | Type | Required | Notes |
|---|---|---|---|
code |
string | Yes | Unique within the company. |
name |
string | Yes | Display name. |
description |
string | No | Free-text description. |
parentId |
guid | No | The parent cost center's id, for hierarchical structures. |
isActive |
boolean | No | If omitted it is saved as false (inactive); send true for an active record. |
| Field | Type | Required | Notes |
|---|---|---|---|
code |
string | Yes | Unique within the company. |
name |
string | Yes | Display name. |
description |
string | No | Free-text description. |
isDefault |
boolean | No | Marks this book as the default. It is stored as sent; the API does not clear the flag on other books, so if you set one, clear the previous one yourself. |
isActive |
boolean | No | If omitted it is saved as false (inactive); send true for an active record. |
| Field | Type | Required | Notes |
|---|---|---|---|
code |
string | Yes | Unique within the company. |
name |
string | Yes | Display name. |
email |
string | No | Contact email address. |
phone |
string | No | Contact phone number. |
department |
string | No | Department name. |
isActive |
boolean | No | If omitted it is saved as false (inactive); send true for an active record. |
| Field | Type | Required | Notes |
|---|---|---|---|
code |
string | Yes | Unique within the company. |
name |
string | Yes | Display name. |
email |
string | No | Contact email address. It is included in the POST/PUT response. |
phone |
string | No | Contact phone number. |
department |
string | No | Department name. |
jobTitle |
string | No | Job title. |
isActive |
boolean | No | If omitted it is saved as false (inactive); send true for an active record. |
Was this page helpful?