> ## 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. # Start a human call > Rings the counsellor's phone and, when they answer, dials `phone_number` and connects them, on your account's calling provider. Every check runs first; a call that cannot go out now is refused, never queued. Scope: `human_calls:write`. ## OpenAPI ````yaml /api-reference/openapi.json post /human-calls 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: post: tags: - Human calls summary: Start a human call description: >- Rings the counsellor's phone and, when they answer, dials `phone_number` and connects them, on your account's calling provider. Every check runs first; a call that cannot go out now is refused, never queued. Scope: `human_calls:write`. operationId: createHumanCall parameters: - name: Idempotency-Key in: header required: false schema: type: string maxLength: 255 description: >- Any unique string per click, e.g. `lead-8812-call-1`. A retry with the same key and body returns the first call instead of ringing the counsellor again; a different body is refused (409). Honoured for 24 hours. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateHumanCall' example: counsellor_email: priya@school.in phone_number: '+919876543210' contact: name: Asha Verma external_id: lead-8812 metadata: crm_owner: u_42 analyze: true responses: '200': description: >- Replay: a call with this `Idempotency-Key` already exists and is returned unchanged (`idempotent_replay: true`). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/HumanCall' '201': description: The call was placed. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/HumanCall' example: id: hcall_7d2e9b1c4a6f8e0d3b5c7a9e object: human_call status: ringing_counsellor counsellor: id: 5f0c2b7e-8a1d-4c3e-9b6f-1a2b3c4d5e6f name: Priya Sharma email: priya@school.in phone_number: '+919876543210' contact: name: Asha Verma email: null external_id: lead-8812 crm_lead_linked: true metadata: crm_owner: u_42 analyze: true status_updates: realtime created_at: '2026-10-17T05:30:02Z' dialed_at: '2026-10-17T05:30:03Z' answered_at: null ended_at: null duration_seconds: null recording_url: null recording_expires_at: null disposition: null analysis: status: pending cost: null '400': description: The request is not valid. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_request: value: error: code: invalid_request message: >- Send exactly one of counsellor_id or counsellor_email. List counsellors with GET /v1/counsellors. request_id: req_8f2c1a7e '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 '402': description: Out of credits (Vacademy Voice only). headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_credits: value: error: code: insufficient_credits message: >- This account is out of calling credits. Top up to place calls. 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 such human call, or no such counsellor in 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 hcall_… not found. request_id: req_8f2c1a7e counsellor_not_found: value: error: code: counsellor_not_found message: >- No active counsellor or admin priya@school.in in this account. List them with GET /v1/counsellors. request_id: req_8f2c1a7e '409': description: >- The counsellor or the number is already on a call, or the Idempotency-Key conflicts. 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: counsellor_busy: value: error: code: counsellor_busy message: >- This counsellor is already on a call. Retry when it ends. request_id: req_8f2c1a7e call_in_progress: value: error: code: call_in_progress message: A call to this number is already in progress. request_id: req_8f2c1a7e idempotency_key_reused: value: error: code: idempotency_key_reused message: >- This Idempotency-Key was already used for a different call. request_id: req_8f2c1a7e request_in_progress: value: error: code: request_in_progress message: >- A request with this Idempotency-Key is still being processed. Retry in 5 seconds. request_id: req_8f2c1a7e conflict: value: error: code: conflict message: >- A conflict without a more specific code; the message says what. request_id: req_8f2c1a7e '422': description: The call cannot be placed now. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: counsellor_cannot_call: value: error: code: counsellor_cannot_call message: >- This counsellor has no mobile number on their profile. Their phone rings first, so add one to their profile. request_id: req_8f2c1a7e telephony_not_configured: value: error: code: telephony_not_configured message: >- Calling is not set up for this account. Connect a calling provider under Settings → Calling. request_id: req_8f2c1a7e outside_calling_hours: value: error: code: outside_calling_hours message: >- Calls are only placed between 09:00 and 21:00 (Asia/Kolkata). request_id: req_8f2c1a7e contact_daily_limit_reached: value: error: code: contact_daily_limit_reached message: >- This number has already been called 3 times in the last 24 hours (limit 3). request_id: req_8f2c1a7e contact_called_recently: value: error: code: contact_called_recently message: This number had a call in the last 60 minutes. request_id: req_8f2c1a7e invalid_request: value: error: code: invalid_request message: >- phone_number is not a number this account's calling provider can dial. 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 '502': description: Your calling provider refused the call. Nothing rang. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: dial_failed: value: error: code: dial_failed message: The calling provider did not place the call. request_id: req_8f2c1a7e '503': description: Your calling provider is briefly unavailable. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' examples: provider_unavailable: value: error: code: provider_unavailable message: >- The calling provider is temporarily unavailable. Retry shortly. request_id: req_8f2c1a7e components: schemas: CreateHumanCall: type: object required: - phone_number properties: counsellor_id: type: string description: >- The counsellor to ring, from `GET /counsellors`. Send this or `counsellor_email`, not both. counsellor_email: type: string format: email description: The counsellor's email in your account (case-insensitive). phone_number: type: string description: >- The contact to connect, E.164. Formatting is ignored as for AI calls. example: '+919876543210' contact: $ref: '#/components/schemas/Contact' metadata: type: object additionalProperties: true description: >- Anything you want back on the call and its webhooks (at most 8 KB as JSON). analyze: type: boolean default: false description: >- Transcribe and analyse the call once its recording is in (0.15 credits per recorded minute). You get `human_call.analysis_ready`. 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 headers: RequestId: schema: type: string description: Unique id of this request. Quote it to support. 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.