Skip to main content
GET
/
v1
/
organizations
/
{org_id}
/
leads
List Leads/Contacts
curl --request GET \
  --url https://api.example.com/v1/organizations/{org_id}/leads \
  --header 'X-API-Key: <x-api-key>'
{
  "success": true,
  "count": 123,
  "total": 123,
  "page": 123,
  "page_size": 123,
  "total_pages": 123,
  "leads": [
    {
      "unique_id": "<string>",
      "id": "<string>",
      "phone_number": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email": "<string>",
      "name": "<string>",
      "organization_id": "<string>",
      "user_id": "<string>",
      "tenant_id": "<string>",
      "do_not_call": true,
      "lead_status": "<string>",
      "lead_priority": "<string>",
      "lead_source": "<string>",
      "external_id": "<string>",
      "notes": "<string>",
      "address_line_1": "<string>",
      "address_line_2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "zip_code": "<string>",
      "country": "<string>",
      "company_name": "<string>",
      "company_position": "<string>",
      "company_industry": "<string>",
      "created_at": {},
      "modified_at": {},
      "updated_at": {},
      "Custom Fields": {}
    }
  ],
  "powered_by": "<string>"
}

​
Description

Returns contact leads (individuals) uploaded to an organization. Includes detailed contact information and custom fields. Supports optional pagination and filtering by user, contact group, or phone number. Deleted contacts are automatically excluded.

​
Authentication

​
X-API-Key
string
required
Your Teli API key

​
Path Parameters

​
org_id
string
required
Organization unique_id

​
Query Parameters

​
user_id
string
Filter leads by user unique_id. Returns only leads uploaded by this user. Returns 404 if user_id does not exist.
​
is_admin
string
default:"false"
Set to true to return all organization leads regardless of user. When false, requires user_id to filter by user.
​
group_id
string
Filter leads by contact group unique_id. Only returns leads that belong to this group.
​
phone_number
string
Filter leads by exact phone number match.
​
page
integer
Page number for pagination (starts at 1). When omitted, all results are returned without pagination.
​
page_size
integer
default:"50"
Number of results per page (max 200). Only used when page is provided.

​
Response Fields

​
success
boolean
Whether the request was successful
​
count
integer
Number of leads returned in this response
​
total
integer
Total number of matching leads across all pages
​
page
integer
Current page number (only present when page query param is used)
​
page_size
integer
Results per page (only present when page query param is used)
​
total_pages
integer
Total number of pages (only present when page query param is used)
​
leads
array
Array of lead/contact objects
​
powered_by
string
Always returns “Teli”

​
Example Requests

Basic
curl -X GET "https://api.teli.ai/v1/organizations/{org_id}/leads" \
  -H "X-API-Key: YOUR_API_KEY"
With Filters
curl -X GET "https://api.teli.ai/v1/organizations/{org_id}/leads?user_id={user_id}&group_id={group_id}&phone_number=+15551234567" \
  -H "X-API-Key: YOUR_API_KEY"
With Pagination
curl -X GET "https://api.teli.ai/v1/organizations/{org_id}/leads?page=1&page_size=50&is_admin=true" \
  -H "X-API-Key: YOUR_API_KEY"

​
Example Responses

200 (Without Pagination)
{
  "success": true,
  "count": 1,
  "total": 1,
  "leads": [
    {
      "unique_id": "1762896414634x733468691531460383",
      "id": "cd5167ad-db4f-43ee-b127-52c6bdaf0d09",
      "phone_number": "+15551234567",
      "first_name": "John",
      "last_name": "Doe",
      "email": "",
      "organization_id": "4d051118-c116-4923-8ff4-1a9761115fec",
      "user_id": "0cf76f73-a751-4f65-b7bf-37f6cd5fdced",
      "tenant_id": "your_tenant",
      "do_not_call": false,
      "lead_status": null,
      "lead_priority": null,
      "lead_source": null,
      "external_id": null,
      "notes": null,
      "address_line_1": null,
      "city": null,
      "state": null,
      "zip_code": null,
      "country": null,
      "created_at": "2025-11-11T21:26:54.723257",
      "modified_at": "2025-11-11T21:26:54.723257",
      "updated_at": "2025-11-11T21:26:54.723257+00:00"
    }
  ],
  "powered_by": "Teli"
}
200 (With Pagination)
{
  "success": true,
  "count": 50,
  "total": 1250,
  "page": 1,
  "page_size": 50,
  "total_pages": 25,
  "leads": ["..."],
  "powered_by": "Teli"
}
404 (Invalid User)
{
  "error": "User 'invalid_user_id' not found",
  "success": false,
  "powered_by": "Teli"
}

​
Custom Fields

The API supports extensive custom fields for different industries:

​
Financial/Lending

  • fico_score, loan_balance, interest_rate, loan_monthly_payment
  • debt_balance, debt_monthly_payment, debt_type
  • heloc_balance, rev_balance, savings
  • lender_name, mortgage_date, months_since_mortgage_open

​
Business/Company

  • company_name, company_position, company_industry
  • company_address_line_1, company_city, company_state

​
Other

  • sso, tax, value, years_worked, total_cc_debt

​
Notes

  • Leads can be uploaded via CSV or API
  • Phone numbers must be in E.164 format
  • Do-not-call list is automatically enforced
  • Leads can be grouped into contact lists for campaigns
  • Custom fields support various industry verticals
  • Deleted contacts are automatically excluded from results
  • Pagination is opt-in: omit the page parameter to get all results (existing behavior)
  • When using user_id with is_admin=false, the user must exist or a 404 is returned