Leads

People who called, chatted or filled in a form. Reading needs leads:read, creating needs leads:write (plus outbound:write to request an AI callback).

Endpoints

GET/leadsList leads
POST/leadsCreate a lead
GET/leads/{lead}Get a lead

List leads

GET/leads

Needs the leads:read scope

Your leads, newest first.

Query parameters

phone_numberstringOptional
Leads with this phone number, in any common US format.
Up to 32 characters
emailstring (email)Optional
Up to 255 characters
sincestring (date-time)Optional
Leads created at or after this time (ISO 8601).
untilstring (date-time)Optional
Leads created before this time (ISO 8601).
per_pageintegerOptional
How many items per page, 1 to 100.
Minimum 1 · Maximum 100
cursorstring | nullOptional
The meta.next_cursor (or meta.prev_cursor) of the previous page.
Up to 1024 characters

Returns

Paginated set of LeadResource

dataarray of objectsRequired
linksobjectRequired
metaobjectRequired

Responses

200Paginated set of LeadResource
401The API key is missing, invalid, expired or revoked.
403The key does not have the leads:read scope.
422Validation error
429Too many requests for this key. Wait for the Retry-After seconds.

curl https://vocenya.com/api/public/v1/leads \
  -H "Authorization: Bearer $VOCENYA_API_KEY"

Response 200

{
  "data": [
    {
      "id": 1,
      "livemode": true,
      "name": "Maria Rivera",
      "phone_number": "+15125550123",
      "email": "[email protected]",
      "reason": "string",
      "urgency": "high",
      "details": {},
      "custom_fields": {},
      "source": "api",
      "call_id": 1,
      "chat_id": 1,
      "outbound_call_id": 1,
      "created_at": "2026-10-02T14:03:11+00:00"
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "path": "string",
    "per_page": 1,
    "next_cursor": "string",
    "prev_cursor": "string"
  }
}

Create a lead

POST/leads

Needs the leads:write scope

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

namestring | nullOptional
Up to 255 characters
phone_numberstring | nullOptional
A US phone number in any common format. Needed for a callback.
Up to 32 characters
emailstring (email) | nullOptional
Up to 255 characters
reasonstringRequired
Why they got in touch.
Up to 2000 characters
urgencystring | nullOptional
Up to 50 characters
detailsarray of strings | nullOptional
Any extra fields you want to keep with the lead (up to 50 keys).
Up to 50 items
callbackobjectOptional
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.

Returns

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

dataobjectRequired
callbackobject | nullRequired

Responses

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

curl -X POST https://vocenya.com/api/public/v1/leads \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Maria Rivera",
  "email": "[email protected]",
  "reason": "Wants a quote for a water heater replacement",
  "urgency": "high",
  "callback": {
    "consent_text": "I agree to receive an automated AI phone call from Rivera Plumbing about my request."
  }
}'

Response 201

{
  "data": {
    "id": 1,
    "livemode": true,
    "name": "Maria Rivera",
    "phone_number": "+15125550123",
    "email": "[email protected]",
    "reason": "string",
    "urgency": "high",
    "details": {},
    "custom_fields": {},
    "source": "api",
    "call_id": 1,
    "chat_id": 1,
    "outbound_call_id": 1,
    "created_at": "2026-10-02T14:03:11+00:00"
  },
  "callback": {
    "id": 1,
    "livemode": true,
    "source": "speed_to_lead",
    "purpose": "marketing",
    "status": "queued",
    "contact_name": "Maria Rivera",
    "phone_number": "+15125550123",
    "blocked_reason": "string",
    "blocked_reason_message": "string",
    "scheduled_for": "string",
    "attempts": 1,
    "answered_at": "2026-10-02T14:03:11+00:00",
    "answered_by": "human",
    "voicemail_left_at": "2026-10-02T14:03:11+00:00",
    "ended_at": "2026-10-02T14:03:11+00:00",
    "duration_seconds": 1,
    "summary": "string",
    "transcript": [
      {
        "role": "string",
        "text": "string"
      }
    ],
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}

Get a lead

GET/leads/{lead}

Needs the leads:read scope

Path parameters

leadintegerRequired
The lead id.

Returns

LeadResource

dataobjectRequired

Responses

200LeadResource
401The API key is missing, invalid, expired or revoked.
403The key does not have the leads:read scope.
404No record with that id belongs to your account.
429Too many requests for this key. Wait for the Retry-After seconds.

curl https://vocenya.com/api/public/v1/leads/311 \
  -H "Authorization: Bearer $VOCENYA_API_KEY"

Response 200

{
  "data": {
    "id": 1,
    "livemode": true,
    "name": "Maria Rivera",
    "phone_number": "+15125550123",
    "email": "[email protected]",
    "reason": "string",
    "urgency": "high",
    "details": {},
    "custom_fields": {},
    "source": "api",
    "call_id": 1,
    "chat_id": 1,
    "outbound_call_id": 1,
    "created_at": "2026-10-02T14:03:11+00:00"
  }
}