Catalogs and master data

API: Catalogs and master data

This page assumes the X-Api-Key header and the ?companyId= parameter described in the REST API for developers overview.

Catalog endpoints

GET /api/v1/Locations (and the other catalogs)

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.

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.id field of any asset returned by GET /api/v1/Assets, or from the application. The old asset categories were retired from the product and from the API.

Writing Master data

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 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/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, for example `"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	The parent cost center's 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	Marks this book as the default. Only one book can be the 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. 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	Defaults to `true`.

Was this page helpful?

Previous Assets and companies Next Accounting