Lookups & Master Data

API: Lookups & Master Data

This page requires the X-Api-Key header and ?companyId= parameter described in the Developer REST API overview.

Lookup endpoints

GET /api/v1/categories (and other lookups)

All lookup endpoints follow the same shape. Use them to resolve ids before creating or updating assets.

curl -s "https://acme.activohq.cloud/api/v1/categories?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY"

Available lookup paths:

Path	Returns
`GET /api/v1/categories`	Asset categories
`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.

Master-data writes

All six lookup resources also accept POST (create) and PUT (update). The same X-Api-Key header and ?companyId= parameter are required.

Rule	Detail
POST success	`201 Created` -- `Location` header points to the new resource; body contains `{id, code, name}` (employees also include `email`).
PUT success	`200 OK` -- body contains the updated `{id, code, name}`. PUT path appends `/{id}`, e.g. `PUT /api/v1/locations/{id}`.
Duplicate code	`400 Bad Request` -- `{"error":"Code already in use."}`.
Unknown id on PUT	`404 Not Found`.
Required fields	`code` and `name` on every resource.

curl example -- POST /api/v1/locations

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" }

POST + PUT /api/v1/categories

Field	Type	Required	Notes
`code`	string	Yes	Unique within the company.
`name`	string	Yes	Display name.
`description`	string	No	Free-text description.
`defaultUsefulLifeMonths`	integer	Yes	Default useful life assigned when creating assets in this category.
`depreciationMethod`	string	No	`StraightLine`, `DecliningBalance`, or `UnitsOfProduction`.
`decliningBalanceFactor`	decimal	No	Multiplier for declining-balance (e.g. `2.0` for double-declining).
`assetAccountCode`	string	No	GL account for the asset cost.
`accumulatedDepreciationAccountCode`	string	No	GL account for accumulated depreciation.
`depreciationExpenseAccountCode`	string	No	GL account for depreciation expense.
`gainLossOnDisposalAccountCode`	string	No	GL account for gain/loss on disposal.
`disposalClearingAccountCode`	string	No	GL clearing account on disposal.
`revaluationSurplusAccountCode`	string	No	GL account for revaluation surplus.
`impairmentLossAccountCode`	string	No	GL account for impairment loss.
`isActive`	boolean	No	Defaults to `true`.

POST + PUT /api/v1/locations

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, e.g. `"PA"`).
`isActive`	boolean	No	Defaults to `true`.

POST + PUT /api/v1/cost-centers

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	Parent cost center id for hierarchical structures.
`isActive`	boolean	No	Defaults to `true`.

POST + PUT /api/v1/depreciation-books

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	Mark this book as the default. Only one book can be default at a time.
`isActive`	boolean	No	Defaults to `true`.

POST + PUT /api/v1/custodians

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	Defaults to `true`.

POST + PUT /api/v1/employees

Field	Type	Required	Notes
`code`	string	Yes	Unique within the company.
`name`	string	Yes	Display name.
`email`	string	No	Contact email address. 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	Defaults to `true`.

Was this page helpful?

Previous Assets & Companies Next Accounting