List leads

GET/v1/leads

Scope: leads:read

Leads in your organization, newest first. Filter by campaign, revenue range, employee count, industry, title or a search term, and page through the results with limit and offset.

Headers

AuthorizationstringRequired
Bearer followed by a space and your API key, for example Bearer vk_….

Query parameters

campaign_idstring · uuid or null
Filter by campaign ID
min_revenueinteger or null
Minimum annual revenue filter
≥ 0
max_revenueinteger or null
Maximum annual revenue filter
≥ 0
min_employeesinteger or null
Minimum employee count filter
≥ 0
max_employeesinteger or null
Maximum employee count filter
≥ 0
industrystring or null
Filter by industry (case-insensitive match)
at most 200 characters
titlestring or null
Filter by job title (case-insensitive partial match)
at most 200 characters
searchstring or null
Up to 5 words, separated by spaces. Every word must match at least one of the lead's email, first name, last name or company.
at most 200 characters
pageinteger
Page number (1-indexed). Prefer offset, which every list route supports
≥ 1Default 1
limitinteger
Results per page (max 100)
≥ 1≤ 100Default 20
offsetinteger or null
Rows to skip before this page. Takes precedence over page when both are sent.
≥ 0

Response

200

totalintegerRequired
Total rows matching the query, across all pages
limitintegerRequired
Page size that was applied
offsetintegerRequired
Rows skipped before this page
has_morebooleanRequired
Whether a further page exists
leadsarray of objectsRequired
Array of leads
Show 17 child attributesHide child attributes
- idstringRequired
  Lead UUID
  Example "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
- created_atstring · date-timeRequired
  When the lead was created
  Example "2024-01-15T10:30:00+00:00"
- annual_revenueinteger or null
  Company annual revenue in dollars
  Example 5000000
- companystring or null
  Company name
  Example "Acme Corp"
- company_websitestring or null
  Lead's company website URL
  Example "https://acmecorp.com"
- custom_fieldsobject or null
  Custom fields as key-value pairs
- delivered_atstring · date-time or null
  When a lead-database result was delivered to your workspace; null for leads from other sources
  Example "2026-09-01T09:00:00+00:00"
- emailstring or null
  Lead's email address
  Example "sarah.johnson@acmecorp.com"
- employeesinteger or null
  Number of employees at the company
  Example 150
- first_namestring or null
  Lead's first name
  Example "Sarah"
- industrystring or null
  Industry sector
  Example "Technology"
- last_namestring or null
  Lead's last name
  Example "Johnson"
- linkedin_urlstring or null
  Lead's LinkedIn profile URL
  Example "https://linkedin.com/in/sarahjohnson"
- phone_numberstring or null
  Phone number
  Example "+1-555-123-4567"
- qualification_scorenumber or null
  Lead qualification score (0-100)
  Example 85.5
- sourcestring or null
  Where the lead came from: lead_database for a licensed lead-database result, csv for an upload, manual for one entered by hand, linkedin_search for a LinkedIn search; null for leads recorded before sources were tracked
  Example "lead_database"
- titlestring or null
  Job title
  Example "VP of Sales"
countintegerRequired
Leads in this page
pageintegerRequired
Current page number. Prefer offset, which every list route returns
successboolean
Default true

Errors

Errors share one JSON body: success, error, message, optional details, and request_id.

Status	Code	Meaning
400	VALIDATION_ERROR	The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`.
401	UNAUTHORIZED	The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated.
401	API_KEY_EXPIRED	The API key is past its expiry date. Create a new key in the Victoria AI app.
403	INSUFFICIENT_SCOPE	The API key doesn't have the scope this endpoint requires, such as `leads:write`.
403	ORGANIZATION_DEACTIVATED	The organization that owns this API key has been deactivated.
429	RATE_LIMITED	Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See Rate limits.
500	INTERNAL_ERROR	Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support.
503	UPSTREAM_TIMEOUT	A service the API depends on timed out. The request is safe to retry.
503	AUTH_UNAVAILABLE	The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry.

Response headers

Header	Description
`X-Request-ID`	Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead.
`RateLimit-Limit`	Requests allowed to this endpoint per minute.
`RateLimit-Remaining`	Requests you can still send to this endpoint right now.
`RateLimit-Reset`	Seconds until the endpoint's full limit is available again.
`Retry-After`	On a `429`: seconds to wait before retrying.