Leads Endpoints

The leads tag provides endpoints for retrieval and updates.

List Workspace Leads

GET /v2/leads

Retrieves leads for the workspace with filters, sorting, and cursor pagination.

Query Parameters

Name	Type	Description
sort_by	string	newest_first, oldest_first, last_touch_first, last_touch_last, most_engaged_first, least_engaged_first
start_date	string (YYYY-MM-DD)	Start date in UTC
end_date	string (YYYY-MM-DD)	End date in UTC
days	integer	Overrides start_date/end_date with a rolling range
status	string	NEW, QUALIFIED, DISQUALIFIED
company_public_id	string	Company LinkedIn handle or numeric id
post_id	string	Filter by originating post. Obtain post IDs from the Content team feed endpoint
email_enriched	boolean	`true` = enriched emails only, `false` = non-enriched only, omit = all leads
cursor	string	Cursor token from previous response page
limit	integer (1–50)	Max leads per page. Default 50

Tip

When both days and start_date are provided, days takes precedence.

Example Request

curl -G "https://api.teamfluence.com/v2/leads" \
  -H "Authorization: Bearer $TEAMFLUENCE_API_KEY" \
  --data-urlencode "days=14" \
  --data-urlencode "status=NEW" \
  --data-urlencode "sort_by=most_engaged_first"

import os
import requests

response = requests.get(
    "https://api.teamfluence.com/v2/leads",
    headers={"Authorization": f"Bearer {os.environ['TEAMFLUENCE_API_KEY']}"},
    params={
        "days": 14,
        "status": "NEW",
        "sort_by": "most_engaged_first",
    },
    timeout=30,
)

print(response.status_code)
print(response.json())

const params = new URLSearchParams({
  days: "14",
  status: "NEW",
  sort_by: "most_engaged_first",
});

const response = await fetch(`https://api.teamfluence.com/v2/leads?${params.toString()}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.TEAMFLUENCE_API_KEY}`,
    Accept: "application/json",
  },
});

console.log(response.status);
console.log(await response.json());

Response Shape

Field	Type	Notes
total	integer	Total leads count
has_more	boolean	Whether additional pages exist
cursor	string \| null	Cursor for next page
items	array	Lead items for this page

Lead Item Fields

Field	Type	Notes
id	string	Lead identifier
first_name	string \| null
last_name	string \| null
headline	string \| null	LinkedIn headline
job_title	string \| null
username	string \| null	LinkedIn username
linkedin_url	string \| null
contact_email	string \| null	Enriched email if available
phone_number	string \| null
enrichment_status	string \| null	Email enrichment state
team_member_email	string \| null	Team member who sourced the lead
source	string \| null	How the lead was captured
source_content_url	string \| null	URL of the originating post
status	string \| null	NEW, QUALIFIED, DISQUALIFIED
tags	string[]	Label list
engagement_events_count	integer \| null	Raw event count
engagement_score	integer \| null	Computed score (0–100)
is_icp_match	boolean	Whether lead matches ICP criteria
is_account_based	boolean	Account-based flag
history	array	Shallow history records
picture	string \| null	Profile picture URL
followers_count	integer \| null
connections_count	integer \| null
country	string \| null
created_at	string (datetime)	Lead creation timestamp (UTC)
last_engagement_dt	string \| null	Most recent engagement timestamp
company	object \| null	Nested company details

Example Response

{
  "total": 1,
  "has_more": false,
  "cursor": null,
  "items": [
    {
      "id": "lead_abc123",
      "first_name": "Jane",
      "last_name": "Smith",
      "headline": "VP of Marketing at Acme Corp",
      "job_title": "VP of Marketing",
      "username": "jane-smith",
      "linkedin_url": "https://www.linkedin.com/in/jane-smith",
      "contact_email": "jane@acme.com",
      "phone_number": null,
      "enrichment_status": "ENRICHED",
      "team_member_email": "owner@example.com",
      "source": "POST",
      "source_content_url": "https://www.linkedin.com/feed/update/urn:li:activity:123456",
      "status": "NEW",
      "tags": ["enterprise", "fintech"],
      "engagement_events_count": 5,
      "engagement_score": 82,
      "is_icp_match": true,
      "is_account_based": false,
      "history": [],
      "picture": "https://my.teamfluence.app/placeholders/default-profile.png",
      "followers_count": 1200,
      "connections_count": 500,
      "country": "US",
      "feed_updated_at": "2026-08-01T09:15:00Z",
      "created_at": "2026-07-15T14:30:00Z",
      "last_engagement_dt": "2026-08-01T09:15:00Z",
      "company": {
        "name": "Acme Corp",
        "slug": "acme-corp",
        "website_url": "https://acme.com",
        "employees_num_min": 201,
        "employees_num_max": 500,
        "headquarters": "San Francisco, CA",
        "country": "US",
        "founded_year": 2012,
        "industries": ["Software Development"],
        "linkedin_url": "https://www.linkedin.com/company/acme-corp",
        "created_at": "2026-06-01T00:00:00Z"
      }
    }
  ]
}

Update Lead

PATCH /v2/leads/{lead_id}

Updates a lead's status, tags, note, CRM information, and ICP match state.

Path Parameter

Name	Type	Required
lead_id	string	yes

Request Body Fields (LeadUpdatePayload)

Field	Type	Notes
status	string \| null	NEW, QUALIFIED, DISQUALIFIED
tags	string[] \| null	Updates tag list
note	object \| null	Note payload
crm_id	string \| null	External CRM identifier
crm_contact_url	string \| null	CRM contact URL
is_icp_match	boolean \| null	ICP match flag

Note Object

Field	Type	Notes
note_id	string \| null	If omitted or null, a new note is created
note_content	string	Note text

Example Request

curl -X PATCH "https://api.teamfluence.com/v2/leads/<lead_id>" \
  -H "Authorization: Bearer $TEAMFLUENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "DISQUALIFIED",
    "tags": ["not-a-fit"],
    "is_icp_match": false,
    "note": {
      "note_id": null,
      "note_content": "Outside target region"
    }
  }'

import os
import requests

lead_id = "lead_123"
payload = {
    "status": "DISQUALIFIED",
    "tags": ["not-a-fit"],
    "is_icp_match": False,
    "note": {
        "note_id": None,
        "note_content": "Outside target region",
    },
}

response = requests.patch(
    f"https://api.teamfluence.com/v2/leads/{lead_id}",
    headers={
        "Authorization": f"Bearer {os.environ['TEAMFLUENCE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json=payload,
    timeout=30,
)

print(response.status_code)
print(response.text)

const leadId = "lead_123";

const response = await fetch(`https://api.teamfluence.com/v2/leads/${leadId}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.TEAMFLUENCE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    status: "DISQUALIFIED",
    tags: ["not-a-fit"],
    is_icp_match: false,
    note: {
      note_id: null,
      note_content: "Outside target region",
    },
  }),
});

console.log(response.status);
console.log(await response.text());

Responses

200: update accepted
422: validation error