Skip to content
vocapable.Docs

Withdraw a candidate without changing an existing qualified serving route

POST
/v1/agents/{agent_id}/receptionist-release/candidate/withdraw
curl --request POST \
  --url https://api.vocapable.com/v1/agents/example/receptionist-release/candidate/withdraw \
  --header 'Authorization: Bearer <token>'

Close the candidate and return its line to unrouted.

The immutable candidate version stays in history; only the ledger row closes. The line is cleared only while it still routes directly to this agent and the agent is still unqualified, so a withdrawal can never clear a route that answers with a qualified version. Clearing, like the routing PATCH, needs no carrier and no production key.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
agent_id
required
Agent Id
string

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
Any of:
string

Unique key for this request, so a retry replays the original result instead of repeating the work. Stored for 24 hours; a replayed response carries Idempotent-Replay: true. A UUID is the documented shape.

Responses

Section titled “Responses”

200

Section titled “200”

Successful Response

Media typeapplication/json
ReceptionistReleaseCandidate

One staged candidate and its lifecycle.

While status is staged the line routes directly to the agent, whose active version is this unqualified candidate: carrier ingress answers only a challenge-verified carrier canary with it and gives every other caller the deterministic fallback. The candidate closes as qualified when the matching qualified version is published, withdrawn when its route is removed, or superseded by a restaged candidate.

object
id
required
Id
string
agent_definition_id
required
Agent Definition Id
string
agent_version_id
required
Agent Version Id
string
version
required
Version
integer
phone_number_id
required
Phone Number Id
string
status
required
Status
string
Allowed values: staged qualified withdrawn superseded
staged_by
Any of:
string
staged_at
required
Staged At
string format: date-time
qualified_version_id
Any of:
string
qualified_at
Any of:
string format: date-time
closed_at
Any of:
string format: date-time
Example
{
  "status": "staged"
}

422

Section titled “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
Examplegenerated
{
  "detail": [
    {
      "loc": [
        "example"
      ],
      "msg": "example",
      "type": "example",
      "input": "example",
      "ctx": {}
    }
  ]
}