Cases

The Cases endpoints provide a lightweight case management system for tracking multi-step operational workflows, escalations, customer complaints, follow-up work, and anything that spans multiple jobs or interactions.

POST /cases/create

Create a new case. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`title`	string	Yes	Case title
`type`	string	Yes	Case type (e.g. `escalation`, `complaint`, `follow_up`)
`description`	string	No	Detailed description
`priority`	string	No	Priority level (`low`, `medium`, `high`, `critical`)
`actor_type`	string	No	Who created the case (`user`, `system`, `automation`)
`actor_id`	integer	No	ID of the creating actor
`tags`	object	No	Tags for categorisation
`metadata`	object	No	Arbitrary metadata
`due_date`	number	No	Due date (unix timestamp)

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/cases/create" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "title": "Repeat boiler failure at Tesco Manchester",
    "type": "escalation",
    "priority": "high",
    "description": "Third callout in 6 weeks for the same unit. Needs senior engineer assessment."
  }'

GET /cases/list

List cases with optional filtering. Query parameters:

Param	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`status`	string	No	Filter by status
`type`	string	No	Filter by case type
`priority`	string	No	Filter by priority
`owner_id`	integer	No	Filter by case owner
`search`	string	No	Full-text search across case titles and descriptions
`page`	integer	No	Page number
`per_page`	integer	No	Results per page

curl -G "https://api.vh3connect.io/api:kP8T1CK7/cases/list" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "status=open" \
  --data-urlencode "priority=high"

GET /cases/search

Full-text search across all cases.

curl -G "https://api.vh3connect.io/api:kP8T1CK7/cases/search" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key" \
  --data-urlencode "q=boiler Manchester"

GET /cases/

Retrieve a specific case with full details.

curl -G "https://api.vh3connect.io/api:kP8T1CK7/cases/case-001" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key"

PATCH /cases/

Update a case (title, description, priority, status, etc.).

curl -X PATCH "https://api.vh3connect.io/api:kP8T1CK7/cases/case-001" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "priority": "critical"
  }'

POST /cases//transition

Transition a case to a new status.

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/cases/case-001/transition" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "status": "resolved"
  }'

POST /cases//comments

Add a comment to a case.

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/cases/case-001/comments" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "body": "Senior engineer booked for Friday. Parts on order."
  }'

GET /cases//activity

Retrieve the full activity timeline for a case, all updates, comments, transitions, and linked items.

curl -G "https://api.vh3connect.io/api:kP8T1CK7/cases/case-001/activity" \
  --data-urlencode "company_id=your-company-id" \
  --data-urlencode "api_key=your-api-key"

POST /cases//participants

Add a participant to a case.

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/cases/case-001/participants" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "user_id": "user-42"
  }'

POST /cases//items

Link an item (job, contact, site) to a case.

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/cases/case-001/items" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "item_type": "job",
    "item_id": "12345"
  }'

​Cases

​POST /cases/create

​GET /cases/list

​GET /cases/search

​GET /cases/

​PATCH /cases/

​POST /cases//transition

​POST /cases//comments

​GET /cases//activity

​POST /cases//participants

​POST /cases//items