Record a human's verdict on a reviewed call

POST

/v1/calls/{call_id}/disposition

curl --request POST \
  --url https://api.vocapable.com/v1/calls/example/disposition \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "code": "completed_goal", "sub_code": "example", "notes": "example" }'

Append a human_review disposition and make it the call’s current one.

An append, never an edit. The agent’s original verdict stays exactly as written - the dispositions table carries no updated_at for that reason - and this row becomes what GET /v1/calls/{id} reports. GET /calls/{id}/dispositions shows both.

Reporting only. A disposition authorizes nothing and suppresses nothing: labelling a call opt_out here does not put the number on the internal DNC list, and labelling it completed_goal does not make the contact dialable. Suppression is POST /v1/dnc-entries, which writes the entry, withdraws the consent standing behind the number, and emits optout.recorded.

Authorizations

• HTTPBearer

Parameters

Path Parameters

call_id

required

Call Id

string

Request Body^required

Media typeapplication/json

DispositionOverrideRequest

A human’s verdict on a reviewed call (POST /v1/calls/{id}/disposition).

code is the pinned platform vocabulary (CANON fact 28) - the same list the agent writes, because “what happened on this dial” is one question with one answer set.

This changes the tenant’s own reporting and nothing else. A disposition is not a compliance control: labelling a call opt_out here records an opinion about the call, it does not suppress the number. Suppression is POST /v1/dnc-entries, which writes the DNC entry, withdraws the consent behind the number and emits optout.recorded - none of which this request can do.

object

code

required

Disposition

Terminal outcome of a contact attempt (docs/06-campaign-engine.md).

string

Allowed values: completed_goal completed_no_goal answered_incomplete voicemail_machine no_answer busy failed opt_out wrong_person_opt_out dnc_hit scrub_blocked blocked_by_policy abandoned_no_slot inbound_unavailable browser_unavailable

sub_code

Any of:

string

string

<= 100 characters

null

null

notes

Any of:

string

string

<= 10000 characters

null

null

Responses

201

Successful Response

Media typeapplication/json

DispositionRecordSummary

One row of a call’s disposition history.

dispositions is append-only: a human review adds a row and repoints the call at it rather than editing the agent’s verdict, so a call whose label was corrected reads as two rows and set_by says which was which.

object

id

required

Id

string

call_id

required

Call Id

string

code

required

Disposition

Terminal outcome of a contact attempt (docs/06-campaign-engine.md).

string

Allowed values: completed_goal completed_no_goal answered_incomplete voicemail_machine no_answer busy failed opt_out wrong_person_opt_out dnc_hit scrub_blocked blocked_by_policy abandoned_no_slot inbound_unavailable browser_unavailable

sub_code

Any of:

string

string

null

null

notes

Any of:

string

string

null

null

set_by

required

Set By

string

Allowed values: agent_llm human_review

structured_outcome

Structured Outcome

object

key

additional properties

any

created_at

required

Created At

string format: date-time

Example

{
  "code": "completed_goal",
  "set_by": "agent_llm"
}

422

Validation Error

Media typeapplication/json

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

input

Input

ctx

Context

object

Example^generated

{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}