API: Audit & Lifecycle

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

---

Audit & lifecycle (read-only)

These endpoints expose the data produced by physical inventory counts, asset transfers, check-out / check-in operations, and reservations. All are GET only, require X-Api-Key and ?companyId=, and return the standard paged envelope ({items, total, skip, take}) -- except GET /api/v1/count-sessions/{id}, which returns the object directly.

GET /api/v1/count-sessions

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 items:

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

GET /api/v1/count-sessions/

Single count session -- same fields as above (no envelope).

---

GET /api/v1/count-results

Paged list of count result lines. Narrow with ?sessionId= to fetch results for one session.

Response items:

{
  "id": "...",
  "countSessionId": "...",
  "assetId": "...",
  "epc": "E28011700000020F4B1C0D5A",
  "status": "Found",
  "expectedLocationId": "...",
  "readLocationId": "...",
  "transferApplied": false
}

Possible status values: Found, Missing, Unexpected, Moved.

---

GET /api/v1/transfers

Paged list of asset location transfers (including those auto-generated from a count). Filter with ?assetId=.

Response items:

{
  "id": "...",
  "assetId": "...",
  "fromLocationId": "...",
  "toLocationId": "...",
  "transferDate": "2025-06-05",
  "reason": "Moved during count reconciliation.",
  "sourceCountResultId": "..."
}

sourceCountResultId is null for manually created transfers.

---

GET /api/v1/checkouts

Paged list of asset check-out / check-in records. Filter with ?assetId=.

Response items:

{
  "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.

---

GET /api/v1/reservations

Paged list of asset reservations. Filter with ?assetId=.

Response items:

{
  "id": "...",
  "assetId": "...",
  "employeeId": "...",
  "startDate": "2025-07-01",
  "endDate": "2025-07-05",
  "status": "Confirmed",
  "notes": "Reserved for training session."
}

status values: Pending, Confirmed, Cancelled.

---

Lifecycle actions

The following POST endpoints perform asset lifecycle transitions and post the same Accounting journals as the web app. 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.

POST /api/v1/assets/

Check out an asset to an employee.

Field	Type	Required	Notes
employeeId	guid	Yes	Employee receiving the asset. Use GET /api/v1/employees to list ids.
expectedReturnDate	date (ISO)	No	e.g. "2025-07-15".
notes	string	No	Free-text notes for the checkout.

Business-rule 400 example: {"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" }

---

POST /api/v1/assets/

Return a checked-out asset.

Field	Type	Required	Notes
notes	string	No	Return notes.
condition	string	No	Return condition by enum name: Good, MinorWear, Damaged, or Lost. Defaults to Good.
damageNotes	string	No	Description of damage (relevant when condition is Damaged or Lost).

---

POST /api/v1/assets/

Reserve an asset for an employee over a date range.

Field	Type	Required	Notes
employeeId	guid	Yes	Employee the reservation is for.
startDate	date (ISO)	Yes	First day of the reservation.
endDate	date (ISO)	Yes	Last day of the reservation.
notes	string	No	Free-text notes.

Business-rule 400 example: {"error":"Reservation conflicts with an existing reservation"}.

---

POST /api/v1/reservations/

Cancel an existing reservation. No request body required.

---

POST /api/v1/assets/

Dispose (retire or sell) an asset. Posts the disposal Accounting journal.

Field	Type	Required	Notes
date	date (ISO)	Yes	Disposal date.
proceeds	decimal	Yes	Sale proceeds (use 0 for a write-off / retirement).
retirement	boolean	Yes	true for retirement / write-off; false for sale.
notes	string	No	Free-text notes.

Business-rule 400 example: {"error":"Only active assets can be disposed"}.

---

POST /api/v1/assets/

Post a revaluation or impairment for an asset.

Field	Type	Required	Notes
date	date (ISO)	Yes	Effective date.
type	string	Yes	Revaluation (upward adjustment) or Impairment (downward write-down).
amount	decimal	Yes	Adjustment amount (always positive; type sets the direction).
notes	string	No	Free-text notes.