Sign in

v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-014102371.0 MB
Case

Attach or detach a case's contact

Attaches the case to a specific existing Contact, or detaches it, via a direct contact_id write (VOIP-1253). Send a non-empty contact_id to attach; send an empty string to detach (mirrors bin-conference-manager's pre_flow_id/post_flow_id PUT convention at the HTTP-layer JSON-schema level -- see §5.5.1 for the precise conversion point; a literal empty string is only ever accepted at this outer HTTP layer, never at the internal RPC-layer uuid.UUID struct). The target contact_id must belong to the same customer as the case; a cross-tenant contact_id is rejected as not found. Every attach/detach is recorded as a case_contact_attributed/ case_contact_detached event, queryable via bin-timeline-manager's audit log (no separate resolution history endpoint needed).

put/contact_cases/{id}

Path parameters

idstring uuid required

Request body

contact_idstring required

The contact to attach. Empty string detaches. Deliberately NOT format: uuid (round-6 correction) -- see §5.5.1: the hand-written internal RPC struct's uuid.UUID field cannot unmarshal a literal empty string, so the HTTP-layer oapi-codegen-generated field must stay a plain string and the "" -> uuid.Nil conversion happens explicitly in the PutContactCasesId handler, mirroring PutConferencesId/pre_flow_id's existing pattern exactly.

Example request

{
  "contact_id": "660e8400-e29b-41d4-a716-446655440001"
}

Response

idstring uuid

Unique identifier for the case.

customer_idstring uuid

Unique identifier of the associated customer.

reference_typestring

Origin channel type (e.g. "call", "conversation_message").

reference_idstring

The internal VoIPBin resource ID that reference_type points at (the call ID when reference_type is "call", the conversation ID when reference_type is "conversation_message"), set automatically at case creation time. Never a customer- or agent-supplied value. Empty when no such internal resource ID applies.

contact_idstring uuid

The resolved contact this case is attributed to. Nullable until resolved.

owner_typestring

Type of the case owner.

owner_idstring uuid

ID of the case owner.

status'open' | 'closed'

Case lifecycle status.

opened_atstring date-time

Timestamp when the case was opened. Nullable.

closed_atstring date-time

Timestamp when the case was closed. Nullable.

closed_reasonstring

Reason the case was closed (e.g. "agent_closed", "timeout").

closed_by_typestring

Type of the actor that closed the case (e.g. "agent", "system").

closed_by_idstring uuid

ID of the actor that closed the case. Nullable.

namestring

Optional freeform case name/title, settable only at creation time.

detailstring

Optional freeform case detail, settable only at creation time.

previous_case_idstring uuid

ID of the prior (now-closed) case this case continues from, if any.

tm_createstring date-time

Timestamp when this case was created.

tm_updatestring date-time

Timestamp when this case was last updated.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "peer": {
    "type": "tel",
    "target": "+14155551234",
    "target_name": "John Smith",
    "name": "Main Office",
    "detail": "Primary contact number"
  },
  "local": {
    "type": "tel",
    "target": "+14155551234",
    "target_name": "John Smith",
    "name": "Main Office",
    "detail": "Primary contact number"
  },
  "reference_type": "call",
  "reference_id": "1fe1356f-3f7f-4ff9-9d33-08136b38f506",
  "contact_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "owner_type": "agent",
  "owner_id": "2a2ec0ba-8004-11ec-aea5-439829c92a7c",
  "status": "open",
  "opened_at": "2026-06-01T09:30:00.000000Z",
  "closed_at": "2026-06-02T09:30:00.000000Z",
  "closed_reason": "agent_closed",
  "closed_by_type": "agent",
  "closed_by_id": "2a2ec0ba-8004-11ec-aea5-439829c92a7c",
  "name": "Billing dispute follow-up",
  "detail": "Customer disputes March invoice charges.",
  "previous_case_id": "11111111-0000-0000-0000-000000000001",
  "tm_create": "2026-06-01T09:30:00.000000Z",
  "tm_update": "2026-06-01T09:30:00.000000Z"
}