Assets and companies

API: Assets and companies

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

Endpoints

GET /api/v1/Companies

Lists every company in your tenant. The companyId parameter is not needed.

curl -s "https://acme.activohq.cloud/api/v1/Companies" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY"

Response:

{
  "items": [
    { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "name": "Acme Corp" }
  ],
  "total": 1,
  "skip": 0,
  "take": 50
}

GET /api/v1/Assets

A paged list of Assets. Optionally filter with search (it matches AssetCode, Name or RFID EPC).

curl -s "https://acme.activohq.cloud/api/v1/Assets?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6&search=laptop&skip=0&take=20" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY"

The response items carry the full AssetDto (see below).

GET /api/v1/Assets/

Retrieves a single asset by its GUID.

curl -s "https://acme.activohq.cloud/api/v1/Assets/f47edba8-67fe-42ce-8209-0e20e1abc17e?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY"

The response fields include accumulatedDepreciation and netBookValue (read-only, calculated). Linked records (location, cost center, custodian, depreciation book and assigned employee) come back as { "id", "code", "name" } objects. The asset's classifier comes back in model (the asset model), whose code is empty because models are identified by name.

POST /api/v1/Assets

Creates an asset. Returns 201 Created with a Location header pointing at the new resource.

curl -s -X POST "https://acme.activohq.cloud/api/v1/Assets?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "LAP-0042",
    "name": "Dell Latitude 5540",
    "assetModelId": "b1e2c3d4-e5f6-7890-abcd-ef1234567890",
    "acquisitionDate": "2024-01-15",
    "acquisitionCost": 1250.00,
    "salvageValue": 100.00,
    "usefulLifeMonths": 60,
    "depreciationMethod": "StraightLine",
    "status": "Active",
    "availability": "Available"
  }'

If your plan's asset limit is reached, the API returns 400 with {"error":"Asset limit reached -- upgrade your plan."}.

PUT /api/v1/Assets/

Updates an existing asset. Returns 200 OK with the updated asset.

curl -s -X PUT "https://acme.activohq.cloud/api/v1/Assets/f47edba8-67fe-42ce-8209-0e20e1abc17e?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Api-Key: $ACTIVOHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assetCode": "LAP-0042",
    "name": "Dell Latitude 5540 (updated)",
    "assetModelId": "b1e2c3d4-e5f6-7890-abcd-ef1234567890",
    "acquisitionDate": "2024-01-15",
    "acquisitionCost": 1250.00
  }'

Write body fields (POST / PUT)

All fields are camelCase JSON. Include them when creating or updating an asset.

Field	Type	Required	Notes
`assetCode`	string	Yes	Unique code within the company.
`name`	string	Yes	Display name.
`rfidEpc`	string	No	The RFID electronic product code.
`description`	string	No	Free-text description.
`serialNumber`	string	No	The manufacturer's serial number.
`assetModelId`	guid	Yes	The asset model (the classifier). There is no model catalog endpoint: take the id from an existing asset's `model.id`, or from the application.
`locationId`	guid	No	Use `GET /api/v1/Locations`.
`costCenterId`	guid	No	Use `GET /api/v1/cost-centers`.
`custodianId`	guid	No	Use `GET /api/v1/Custodians`.
`depreciationBookId`	guid	No	Use `GET /api/v1/depreciation-books`.
`assignedEmployeeId`	guid	No	Use `GET /api/v1/Employees`.
`acquisitionDate`	date (ISO)	Yes	For example `"2024-01-15"`.
`inServiceDate`	date (ISO)	No	The date the asset was put into service.
`acquisitionCost`	decimal	Yes	The original acquisition cost.
`salvageValue`	decimal	No	The residual value at the end of the useful life.
`usefulLifeMonths`	integer	No	Used by the straight-line and declining-balance methods.
`totalEstimatedUnits`	integer	No	Used only by the `UnitsOfProduction` method.
`depreciationMethod`	string	No	`StraightLine`, `DecliningBalance`, or `UnitsOfProduction`.
`status`	string	No	`Draft`, `Active`, or the other defined statuses.
`availability`	string	No	`Available` or `CheckedOut`.

Read-only response fields

The AssetDto returned by GET and POST/PUT includes these extra calculated fields:

Field	Notes
`accumulatedDepreciation`	Total depreciation recorded to date.
`netBookValue`	`acquisitionCost - accumulatedDepreciation`.

Was this page helpful?

Previous Developer API Next Catalogs and master data