P4 Software
/
activoHQ English
This page assumes the X-Api-Key header and the ?companyId= parameter described in the REST API for developers overview.
These endpoints expose the data produced by physical inventory counts, asset transfers, check-out /
check-in operations and reservations. Those in this section are GET only, require X-Api-Key and
?companyId=, and return the standard paging envelope ({items, total, skip, take}) - except
GET /api/v1/count-sessions/{id}, which returns the object directly.
A paged list of physical inventory Count sessions.
curl -s "https://acme.activohq.cloud/api/v1/count-sessions?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "X-Api-Key: $ACTIVOHQ_API_KEY"
Response item fields:
{
"id": "...",
"code": "CNT-2025-001",
"name": "Mid-year physical count",
"openedDate": "2025-06-01",
"status": "Reconciled",
"expectedCount": 312,
"reconciledDate": "2025-06-05",
"notes": "Annual mid-year audit."
}
status is Open, Reading, Reconciled or Closed. A new session is created directly in Reading; Open is never assigned. expectedCount counts the company's Assets with Active status when the session was opened.
A single count session - the same fields as above (without the paging envelope).
A paged list of count result lines. Use ?sessionId= to get one session's results.
Response item fields:
{
"id": "...",
"countSessionId": "...",
"assetId": "...",
"epc": "E28011700000020F4B1C0D5A",
"status": "Found",
"expectedLocationId": "...",
"readLocationId": "...",
"transferApplied": false
}
Possible status values: Found, Missing, Unexpected, Moved.
A paged list of asset Location transfers (including those generated automatically from a count). Filter with ?assetId=.
Response item fields:
{
"id": "...",
"assetId": "...",
"fromLocationId": "...",
"toLocationId": "...",
"transferDate": "2025-06-05",
"reason": "RFID reconciliation",
"sourceCountResultId": "..."
}
sourceCountResultId is null on manually created transfers (made with the asset's Transfer action); on those, reason is the text the user typed. On transfers generated by applying a count, reason is RFID reconciliation.
A paged list of asset check-out / check-in records. Filter with ?assetId=.
Response item fields:
{
"id": "...",
"assetId": "...",
"employeeId": "...",
"checkoutDate": "2025-06-10",
"expectedReturnDate": "2025-06-17",
"actualReturnDate": "2025-06-16",
"notes": "Required for field visit.",
"returnCondition": "Good",
"damageNotes": null
}
actualReturnDate is null while the asset is still checked out.
returnCondition values: Good, MinorWear, Damaged, Lost.
A paged list of Asset reservations. Filter with ?assetId=.
Response item fields:
{
"id": "...",
"assetId": "...",
"employeeId": "...",
"startDate": "2025-07-01",
"endDate": "2025-07-05",
"status": "Reserved",
"notes": "Reserved for training session."
}
status values: Reserved, Fulfilled, Cancelled.
The following POST endpoints run asset life-cycle transitions and record the same journal
entries the web application does. They all require X-Api-Key and ?companyId=. On success they
return 200 {"status":"ok"}. Business rule violations return 400 with {"error":"...message..."};
"not found" returns 404.
Check an asset out to an employee.
| Field | Type | Required | Notes |
|---|---|---|---|
employeeId |
guid | Yes | The employee receiving the asset. Use GET /api/v1/Employees to list the ids. |
expectedReturnDate |
date (ISO) | No | For example "2025-07-15". |
notes |
string | No | Free-text notes for the check-out. |
photoBase64 |
string | No | A photo of the asset's condition, base64-encoded (PNG, GIF, JPG or WebP, maximum 5 MB). |
photoContentType |
string | No | The photo's content type, for example image/png. |
eulaAcceptedText |
string | Depends on the model | The text of the agreement accepted. It is required when the asset's model requires an agreement; if missing, the API answers 400 with This asset requires acceptance of the agreement before checkout. To read the agreement use GET /api/v1/Assets/{id}/eula, which returns {"required": true/false, "text": "..."}. |
An example 400 business-rule error: {"error":"Asset is already checked out"}.
curl -s -X POST "https://acme.activohq.cloud/api/v1/Assets/f47edba8-67fe-42ce-8209-0e20e1abc17e/checkout?companyId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
-H "X-Api-Key: $ACTIVOHQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"employeeId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"expectedReturnDate": "2025-07-15",
"notes": "Required for field visit."
}'
Response (200 OK):
{ "status": "ok" }
Check a checked-out asset back in.
| Field | Type | Required | Notes |
|---|---|---|---|
notes |
string | No | Return notes. |
condition |
string | No | The return condition by enum name: Good, MinorWear, Damaged or Lost. Defaults to Good. |
damageNotes |
string | No | A description of the damage (relevant when condition is Damaged or Lost). |
photoBase64 |
string | No | A photo of the asset's condition, base64-encoded (PNG, GIF, JPG or WebP, maximum 5 MB). |
photoContentType |
string | No | The photo's content type, for example image/jpeg. |
Reserve an asset for an employee over a date range.
| Field | Type | Required | Notes |
|---|---|---|---|
employeeId |
guid | Yes | The employee the reservation is for. |
startDate |
date (ISO) | Yes | The reservation's first day. |
endDate |
date (ISO) | Yes | The reservation's last day. |
notes |
string | No | Free-text notes. |
An example 400 business-rule error: {"error":"Reservation conflicts with an existing reservation"}.
Cancel an existing reservation. No request body is needed.
Dispose of (retire or sell) an asset. It records the disposal's journal entry.
| Field | Type | Required | Notes |
|---|---|---|---|
date |
date (ISO) | Yes | The disposal date. |
proceeds |
decimal | Yes | The sale proceeds (use 0 for a write-off / retirement). |
retirement |
boolean | Yes | true for a retirement / write-off; false for a sale. |
notes |
string | No | Free-text notes. |
An example 400 business-rule error: {"error":"Only active Assets can be disposed"}.
Record an asset revaluation or impairment.
| Field | Type | Required | Notes |
|---|---|---|---|
date |
date (ISO) | Yes | The effective date. |
type |
string | Yes | Revaluation (an upward adjustment) or Impairment (a reduction in value). |
amount |
decimal | Yes | The adjustment amount (always positive; type sets the direction). |
notes |
string | No | Free-text notes. |
These calls open, reconcile and close an RFID count session (the mobile app uses them). They need X-Api-Key and ?companyId=, except submitting reads, which carries no companyId.
Opens a session. Body: code (required, unique within the company), name (required) and notes (optional). Returns 201 Created with the session (the same fields as GET /api/v1/count-sessions/{id}). If the code already exists, or code or name is missing, it answers 400 (Session code already exists or code and name are required.).
Submits reads to a session. This route is not under /api/v1 and takes no companyId: the company comes from the session. The body is a JSON array of reads:
[
{ "epc": "E28011700000020F4B1C0D5A", "readTimestamp": "2025-06-01T14:05:00Z", "readerId": "DOCK-01", "locationCode": "HQ-01" }
]
locationCode is optional and matched case-insensitively; an unknown code leaves the read with no location. For an asset with no EPC, send its asset code in epc. Response: 200 {"ingested": n}. An empty array returns 400 (No reads supplied.), an unknown session 404, and a session no longer in Reading status 400 (Session is not accepting reads).
Reconciles the session. Returns 200 with the totals {"found": n, "missing": n, "unexpected": n, "moved": n}. After reconciling, the session no longer accepts reads.
Closes the session. Returns 200 {"status":"ok"}.
Was this page helpful?