> ## Documentation Index > Fetch the complete documentation index at: https://docs.telleo.ai/llms.txt > Use this file to discover all available pages before exploring further. # Set a disposition > Records the call's outcome, as a counsellor does in the dashboard. When the call is filed on a lead and the disposition maps to a lead stage, the lead moves to it. Scope: `human_calls:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /human-calls/{id}/disposition openapi: 3.1.0 info: title: Telleo API version: 1.2.0 description: >- Start AI phone calls, or connect your counsellors to contacts, from your own systems and get each call's outcome back. servers: - url: https://api.telleo.ai/v1 security: - ApiKey: [] tags: - name: Calls - name: Batches - name: Agents - name: Human calls - name: Credits - name: Webhook paths: /human-calls/{id}/disposition: post: tags: - Human calls summary: Set a disposition description: >- Records the call's outcome, as a counsellor does in the dashboard. When the call is filed on a lead and the disposition maps to a lead stage, the lead moves to it. Scope: `human_calls:write`. operationId: setHumanCallDisposition parameters: - name: id in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object required: - key properties: key: type: string description: A key from `GET /dispositions`. example: CALLBACK notes: type: string maxLength: 2000 example: Call after 6 pm responses: '200': description: The human call with its disposition. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/HumanCall' '401': description: The key is missing, unknown, revoked or expired. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_api_key: value: error: code: missing_api_key message: Send your API key in the X-API-Key header. request_id: req_8f2c1a7e invalid_api_key: value: error: code: invalid_api_key message: This API key is not valid. request_id: req_8f2c1a7e '403': description: >- The key lacks the human-call scope this request needs. Keys only have human_calls:read / human_calls:write when created with them. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_scope: value: error: code: insufficient_scope message: This API key does not have the human_calls:write scope. request_id: req_8f2c1a7e '404': description: No human call with this id belongs to your account. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: not_found: value: error: code: not_found message: Human call not found. request_id: req_8f2c1a7e '409': description: The call was never placed. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: call_not_dialed: value: error: code: call_not_dialed message: >- This call was never placed, so it cannot take a disposition. request_id: req_8f2c1a7e '422': description: Unknown disposition key. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: unknown_disposition: value: error: code: unknown_disposition message: >- No disposition NOPE in this account. List them with GET /v1/dispositions. request_id: req_8f2c1a7e '429': description: Too many requests for this key. headers: Retry-After: schema: type: integer description: Seconds to wait before retrying. X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: code: rate_limited message: Too many requests. Retry after 12 seconds. request_id: req_8f2c1a7e components: headers: RequestId: schema: type: string description: Unique id of this request. Quote it to support. schemas: HumanCall: type: object properties: id: type: string example: hcall_7d2e9b1c4a6f8e0d3b5c7a9e object: type: string const: human_call status: type: string enum: - queued - ringing_counsellor - connecting - in_progress - completed - no_answer - busy - failed - canceled status_reason: type: string description: Why a call failed, in plain words. Present only when there is one. no_answer_by: type: - string - 'null' enum: - counsellor - contact - null description: >- Only on `no_answer` / `busy`: which phone did not pick up, when the provider says so. counsellor: type: object properties: id: type: string name: type: - string - 'null' email: type: - string - 'null' phone_number: type: string contact: $ref: '#/components/schemas/Contact' crm_lead_linked: type: boolean description: >- The call was filed on the one lead in your account with this number (it shows on the lead's timeline). metadata: type: object additionalProperties: true analyze: type: boolean status_updates: type: string enum: - realtime - final_only - delayed description: >- How live `status` is on your provider: Vacademy Voice `realtime`, Exotel `final_only`, Airtel `delayed` (after its call record is imported). created_at: type: string format: date-time dialed_at: type: - string - 'null' format: date-time answered_at: type: - string - 'null' format: date-time description: When the contact picked up, when known. ended_at: type: - string - 'null' format: date-time duration_seconds: type: - integer - 'null' recording_url: type: - string - 'null' description: >- A temporary link to the recording (24 hours). Fetch the call again for a fresh link. recording_expires_at: type: - string - 'null' format: date-time disposition: $ref: '#/components/schemas/HumanCallDisposition' analysis: $ref: '#/components/schemas/HumanCallAnalysis' cost: type: - object - 'null' description: >- `null` while the call runs. Only Vacademy Voice talk time is charged to your credits; Exotel and Airtel bill you directly. properties: credits: type: number billed: type: boolean note: type: string enum: - billed_by_provider description: Present when the call ran on your own carrier account. idempotent_replay: type: boolean description: >- Only on `POST /human-calls`: `true` when this is the call created by an earlier request with the same `Idempotency-Key`. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable code. Branch on this, not on the message. example: invalid_request message: type: string description: A sentence you can log or show to an operator. request_id: type: string description: Quote this when you contact support. details: type: object additionalProperties: true description: >- Extra context, e.g. `errors: [{field, message}]` for validation errors or `call_id` for conflicts. Contact: type: object properties: name: type: - string - 'null' maxLength: 120 description: >- How the agent addresses the person. Fills `{{name}}` in the agent's script. email: type: - string - 'null' format: email external_id: type: - string - 'null' maxLength: 255 description: >- Your own id for this person or lead (CRM record id). Echoed back and filterable on `GET /calls`. HumanCallDisposition: type: - object - 'null' description: The outcome recorded by the counsellor or by you. `null` until set. properties: key: type: string example: INTERESTED label: type: - string - 'null' notes: type: - string - 'null' set_at: type: - string - 'null' format: date-time set_by: type: - string - 'null' enum: - counsellor - api - null HumanCallAnalysis: type: object description: >- AI analysis of the conversation. Fields beyond `status` are present once it is `completed`. properties: status: type: string enum: - not_requested - pending - completed - failed reason: type: string description: >- With `failed`: `not_connected`, `no_recording`, `insufficient_credits`, `empty_transcript`, `analysis_error`… A temporary error is retried (up to 4 attempts) and stays `pending` meanwhile. summary: type: - string - 'null' short_update: type: - string - 'null' description: A few words for a list view. call_type: type: - string - 'null' inferred_goal: type: - string - 'null' description: >- What the counsellor was trying to achieve, inferred from the conversation. outcome: type: - string - 'null' description: The call's outcome in a word or two, e.g. `interested`. sentiment: type: - string - 'null' description: The contact's sentiment. conversion_likelihood: type: - string - 'null' counsellor_rating: type: - number - 'null' description: How well the counsellor pursued the call's goal (0–10). outcome_rating: type: - number - 'null' description: How good the outcome was (0–10). language: type: - string - 'null' credits: type: - number - 'null' description: Credits charged for this analysis. completed_at: type: - string - 'null' format: date-time securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: >- Your AI calling API key (`vak_call_…`). `Authorization: Bearer ` also works. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.