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.

These server-to-server endpoints are part of the VH3 AI Intelligence API. Use the base URL https://api.vh3connect.io/api:kP8T1CK7 and send company_id + tenant api_key in the JSON body for writes or as query parameters for reads.

Keep the tenant api_key in server-side environment variables. For interactive Case administration, use VH3 Connect, which authenticates signed-in users without exposing the key.Use only the base URL above for Cases. Never send api_key from browser or mobile code.

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/{case_id}

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/{case_id}

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/{case_id}/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/{case_id}/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/{case_id}/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/{case_id}/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/{case_id}/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"
  }'

POST /cases/{case_id}/assign-team

Set or clear the Assigned Team on a case (case.team_id). Reassignment replaces the current team. Send team_id: 0 to clear. Activity is recorded with actor_type / actor_id. Request body:

Field	Type	Required	Description
`company_id`	string	Yes	Your tenant identifier
`api_key`	string	Yes	Your tenant API key
`team_id`	integer	Yes	Team to assign, or `0` to clear
`actor_type`	string	No	Who performed the action (`user`, `agent`, `system`)
`actor_id`	integer	No	ID of the acting user or agent catalogue row

curl -X POST "https://api.vh3connect.io/api:kP8T1CK7/cases/101/assign-team" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "your-company-id",
    "api_key": "your-api-key",
    "team_id": 42,
    "actor_type": "agent",
    "actor_id": 1
  }'

​Cases

​POST /cases/create

​GET /cases/list

​GET /cases/search

​GET /cases/{case_id}

​PATCH /cases/{case_id}

​POST /cases/{case_id}/transition

​POST /cases/{case_id}/comments

​GET /cases/{case_id}/activity

​POST /cases/{case_id}/participants

​POST /cases/{case_id}/items

​POST /cases/{case_id}/assign-team

Cases

POST /cases/create

GET /cases/list

GET /cases/search

GET /cases/{case_id}

PATCH /cases/{case_id}

POST /cases/{case_id}/transition

POST /cases/{case_id}/comments

GET /cases/{case_id}/activity

POST /cases/{case_id}/participants

POST /cases/{case_id}/items

POST /cases/{case_id}/assign-team