---
title: "Create a lead"
method: POST
path: "/leads"
tags: ["Leads"]
---

# Create a lead

`POST /leads`

## Request

- Base URL: `https://vocenya.com/api/public/v1`
- URL: `https://vocenya.com/api/public/v1/leads`
- Auth: HTTP bearer

Add a lead from your own system, for example a form on another site. It shows up in the portal
and is pushed to your CRM like any other lead.

Send `callback` to have the AI call the person back straight away (speed-to-lead). The key then
also needs the `outbound:write` scope. It needs outbound calling switched on, an active Pro plan and an AI receptionist, and is not available
in HIPAA mode. The call still follows calling hours, Do Not Call lists and daily limits; the
queued call is returned as `callback`.

## Request body

- StoreLeadRequest
  - `name` string, nullable
  - `phone_number` string, nullable: A US phone number in any common format. Needed for a callback.
  - `email` string, email, nullable
  - `reason` string, required: Why they got in touch.
  - `urgency` string, nullable
  - `details` string[], nullable: Any extra fields you want to keep with the lead (up to 50 keys).
  - `callback` object: Ask the AI to call the person back now (speed-to-lead). Only send this when the person agreed to an AI call: `consent_text` must be the exact wording they agreed to. Needs the `outbound:write` scope as well as `leads:write`.
    - `consent_text` string
    - `source_url` string, uri, nullable: The page where they agreed.
    - `ip_address` string, nullable: Their IP address when they agreed.
    - `user_agent` string, nullable: Their browser's user agent when they agreed.

## Response `201`

The lead, and the AI callback when one was requested.

- object
  - `data` LeadResource, required
    - `id` integer, required
    - `livemode` boolean, required: `true` for live data, `false` for test data (created with a `vk_test_` key).
    - `name` string, nullable, required
    - `phone_number` string, nullable, required
    - `email` string, nullable, required
    - `reason` string: Why they got in touch. Not included for HIPAA-mode accounts.
    - `urgency` string, nullable, required
    - `details` object, nullable: Extra fields captured with the lead. Not included for HIPAA-mode accounts.
    - `custom_fields` object: The custom fields the AI collected, as `{key: {label, value}}`. Not included for HIPAA-mode accounts.
    - `source` 'api' | 'call' | 'chat' | 'outbound_call' | 'website', required: Where the lead came from.
    - `call_id` integer, nullable, required
    - `chat_id` integer, nullable, required
    - `outbound_call_id` integer, nullable, required
    - `created_at` string, nullable, required
  - `callback` OutboundCallResource, required
    - `id` integer, required
    - `livemode` boolean, required: `true` for live data, `false` for test data (created with a `vk_test_` key).
    - `source` 'speed_to_lead' | 'agent_dial' | 'campaign' | 'api', required: | | |---| | `speed_to_lead` <br/> The AI calls back someone who just asked to be contacted. | | `agent_dial` <br/> A GH Live agent dials a number by hand from the workspace. | | `campaign` <br/> The AI works through a client's campaign contact list. | | `api` <br/> The client's own system queued an AI call through the public API or platform MCP server. |
    - `purpose` 'marketing' | 'informational', required: Why an outbound call is made. Telemarketing needs prior express written consent for AI voices.
    - `status` 'queued' | 'scheduled' | 'blocked' | 'connecting_agent' | 'dialing' | 'in_progress' | 'completed' | 'no_answer' | 'voicemail' | 'failed', required
    - `contact_name` string, nullable, required
    - `phone_number` string, required
    - `blocked_reason` string, nullable, required: Why the call was blocked or delayed, as a code.
    - `blocked_reason_message` string, nullable, required: Why the call was blocked or delayed, in words.
    - `scheduled_for` string, nullable, required: When a delayed call is due to ring (calling hours, daily limit).
    - `attempts` integer, required
    - `answered_at` string, nullable, required
    - `answered_by` 'human' | 'machine' | 'unknown', required: Who the carrier's answering machine detection heard pick up an outbound AI call. Null when detection gave no result.
    - `voicemail_left_at` string, nullable, required: When the AI finished leaving a message on voicemail, under the account's "leave a message" setting.
    - `ended_at` string, nullable, required
    - `duration_seconds` integer, nullable, required
    - `summary` string, nullable: The AI's summary of the call. Not included for HIPAA-mode accounts.
    - `transcript` object[], nullable: The conversation, turn by turn. Only on `GET /outbound-calls/{id}`, and never for HIPAA-mode accounts.
      - `role` string, required
      - `text` string, required
    - `created_at` string, nullable, required

## Other responses

- `401`: The API key is missing, invalid, expired or revoked.
- `403`: A `callback` was sent but the key does not have the `outbound:write` scope (`missing_scope`).
- `422`: Validation failed, or a callback was requested but cannot be made (`speed_to_lead_unavailable`, `invalid_number`).
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

---

[API](https://skmtc.dev/vocenya/apis/vocenya-api.md) · [All operations](https://skmtc.dev/vocenya/apis/vocenya-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vocenya/apis/vocenya-api/revisions/946913941565?raw)