Contacts
List contacts
Lists LinkedIn contacts
GET
https://api.talktohumans.app
/
v1
/
contacts
List contacts
curl --request GET \
--url https://api.talktohumans.app/v1/contacts \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.talktohumans.app/v1/contacts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.talktohumans.app/v1/contacts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.talktohumans.app/v1/contacts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"contacts": [
{
"account_relationship_id": "1042",
"contact_enrichment": {
"work_email": {
"status": "found"
},
"phone": {
"status": "found"
}
},
"contact_id": "123",
"provider_participant_id": "urn:li:fsd_profile:abc",
"public_identifier": "jane-doe",
"account": {
"account_id": "42",
"display_name": "Jane Doe",
"provider_account_id": "ACoAA000000",
"owner_user_id": "7"
},
"name": "Jane Doe",
"first_name": "Jane",
"last_name": "Doe",
"headline": "Founder at Acme",
"primary_role_title": "Founder",
"primary_company_name": "Acme",
"work_email": "jane@acme.example",
"phone": "+14155550123",
"linkedin_url": "https://www.linkedin.com/in/jane-doe/",
"avatar_url": "https://media.licdn.com/dms/image/example/profile-displayphoto.jpg",
"background_cover_url": "https://media.licdn.com/dms/image/example/profile-cover.jpg",
"relationship_status": "connected",
"Deal stage": "Qualified",
"Lead score": 91,
"Next follow-up": "2026-07-01",
"VIP": true,
"tags": [
{
"name": "Hot lead",
"color": "red"
}
],
"notes": [
{
"note_id": "0b7e4c2a-5d1f-4a8e-9c3b-6f2d1e0a9b8c",
"content": "Follow up next week",
"created_at": "2026-06-24T09:15:00Z"
}
],
"languages": [
{
"language": "English"
}
],
"experiences": [
{
"experience_id": "exp_2f8c1b",
"company_participant_id": "linkedin:participant:urn:li:fsd_company:123",
"company_provider_participant_id": "urn:li:fsd_company:123",
"company_name": "Acme",
"title": "Founder",
"employment_type": "Full-time",
"location": "San Francisco Bay Area",
"start_at": "2021-01",
"is_current": true,
"description": "Building business software for sales teams."
}
],
"educations": [
{
"education_id": "edu_91ac42",
"school_participant_id": "linkedin:participant:urn:li:fsd_company:987",
"school_provider_participant_id": "urn:li:fsd_company:987",
"school_name": "Stanford University",
"degree": "MBA",
"field_of_study": "Business Administration",
"start_at": "2014",
"end_at": "2016"
}
],
"locations": [
{
"linkedin_text": "San Francisco Bay Area",
"display_text": "San Francisco, California, United States",
"country_code": "US",
"region_code": "US-CA",
"country": "United States",
"country_full": "United States",
"state": "California",
"city": "San Francisco",
"geographic_area": "San Francisco Bay Area",
"is_primary": true,
"is_headquarter": false
}
],
"company": {
"company_id": "linkedin:participant:urn:li:fsd_company:123",
"provider_participant_id": "urn:li:fsd_company:123",
"public_identifier": "acme",
"name": "Acme",
"linkedin_url": "https://www.linkedin.com/company/acme/",
"avatar_url": "https://media.licdn.com/dms/image/example/company-logo.jpg",
"background_cover_url": "https://media.licdn.com/dms/image/example/company-cover.jpg",
"headline": "Software Development",
"headcount": "51-200",
"employee_count": 120,
"website_url": "https://acme.example",
"follower_count": 12000,
"about": "Acme builds business software.",
"industries": [
{
"name": "Software Development",
"title": "Software Development",
"industry_urn": "urn:li:industry:4",
"provider_industry_id": "4",
"hierarchy": "Technology > Software"
}
],
"locations": [
{
"linkedin_text": "San Francisco, CA",
"display_text": "San Francisco, California, United States",
"country_code": "US",
"region_code": "US-CA",
"country": "United States",
"country_full": "United States",
"state": "California",
"city": "San Francisco",
"geographic_area": "San Francisco Bay Area",
"is_primary": true,
"is_headquarter": true
}
]
},
"app_url": "https://app.talktohumans.app/contacts"
}
],
"pagination": {
"limit": 10,
"has_more": false
}
}
}
Authorizations
Pass API key as Authorization: Bearer <api_key>.
Query Parameters
LinkedIn account IDs returned by GET /v1/accounts.
Repeat the query parameter for multiple accounts. The backend also accepts comma-separated values.
If an explicit account target is not accessible to this credential, the API returns 403 account_shared_access_required.
Pattern:
^[1-9][0-9]*$Filter by contact ID, including email and phone lookup results.
Pattern:
^[1-9][0-9]*$Search by name, headline, company, role, LinkedIn handle, or profile URL.
Filter by current or past company name.
Filter by headline text.
Search broadly across profile details, tags, notes, locations, work history, education, and company data.
Filter by location text.
Filter by company size or employee count.
Filter by tag name.
Filter by LinkedIn relationship state. Defaults to any.
Available options:
any, connected, not_connected, unknown Filter by invitation state. Only pending is currently supported.
Available options:
pending Return contacts who participate in the given TalkToHumans conversation.
Filter by a saved contact view. Accepts the view id or an unambiguous public_id from GET /v1/views.
Uses the view's account and filters. An explicit account_id scope must include that account.
Results keep the endpoint's normal ordering.
Page size. Defaults to 10. Values above 25 are clamped to 25.
Required range:
1 <= x <= 25Opaque cursor from the previous response's pagination.next_cursor.
Response
Contacts matching the filters.
Show child attributes
Show child attributes
⌘I
List contacts
curl --request GET \
--url https://api.talktohumans.app/v1/contacts \
--header 'Authorization: Bearer <token>'const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.talktohumans.app/v1/contacts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.talktohumans.app/v1/contacts"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.talktohumans.app/v1/contacts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"data": {
"contacts": [
{
"account_relationship_id": "1042",
"contact_enrichment": {
"work_email": {
"status": "found"
},
"phone": {
"status": "found"
}
},
"contact_id": "123",
"provider_participant_id": "urn:li:fsd_profile:abc",
"public_identifier": "jane-doe",
"account": {
"account_id": "42",
"display_name": "Jane Doe",
"provider_account_id": "ACoAA000000",
"owner_user_id": "7"
},
"name": "Jane Doe",
"first_name": "Jane",
"last_name": "Doe",
"headline": "Founder at Acme",
"primary_role_title": "Founder",
"primary_company_name": "Acme",
"work_email": "jane@acme.example",
"phone": "+14155550123",
"linkedin_url": "https://www.linkedin.com/in/jane-doe/",
"avatar_url": "https://media.licdn.com/dms/image/example/profile-displayphoto.jpg",
"background_cover_url": "https://media.licdn.com/dms/image/example/profile-cover.jpg",
"relationship_status": "connected",
"Deal stage": "Qualified",
"Lead score": 91,
"Next follow-up": "2026-07-01",
"VIP": true,
"tags": [
{
"name": "Hot lead",
"color": "red"
}
],
"notes": [
{
"note_id": "0b7e4c2a-5d1f-4a8e-9c3b-6f2d1e0a9b8c",
"content": "Follow up next week",
"created_at": "2026-06-24T09:15:00Z"
}
],
"languages": [
{
"language": "English"
}
],
"experiences": [
{
"experience_id": "exp_2f8c1b",
"company_participant_id": "linkedin:participant:urn:li:fsd_company:123",
"company_provider_participant_id": "urn:li:fsd_company:123",
"company_name": "Acme",
"title": "Founder",
"employment_type": "Full-time",
"location": "San Francisco Bay Area",
"start_at": "2021-01",
"is_current": true,
"description": "Building business software for sales teams."
}
],
"educations": [
{
"education_id": "edu_91ac42",
"school_participant_id": "linkedin:participant:urn:li:fsd_company:987",
"school_provider_participant_id": "urn:li:fsd_company:987",
"school_name": "Stanford University",
"degree": "MBA",
"field_of_study": "Business Administration",
"start_at": "2014",
"end_at": "2016"
}
],
"locations": [
{
"linkedin_text": "San Francisco Bay Area",
"display_text": "San Francisco, California, United States",
"country_code": "US",
"region_code": "US-CA",
"country": "United States",
"country_full": "United States",
"state": "California",
"city": "San Francisco",
"geographic_area": "San Francisco Bay Area",
"is_primary": true,
"is_headquarter": false
}
],
"company": {
"company_id": "linkedin:participant:urn:li:fsd_company:123",
"provider_participant_id": "urn:li:fsd_company:123",
"public_identifier": "acme",
"name": "Acme",
"linkedin_url": "https://www.linkedin.com/company/acme/",
"avatar_url": "https://media.licdn.com/dms/image/example/company-logo.jpg",
"background_cover_url": "https://media.licdn.com/dms/image/example/company-cover.jpg",
"headline": "Software Development",
"headcount": "51-200",
"employee_count": 120,
"website_url": "https://acme.example",
"follower_count": 12000,
"about": "Acme builds business software.",
"industries": [
{
"name": "Software Development",
"title": "Software Development",
"industry_urn": "urn:li:industry:4",
"provider_industry_id": "4",
"hierarchy": "Technology > Software"
}
],
"locations": [
{
"linkedin_text": "San Francisco, CA",
"display_text": "San Francisco, California, United States",
"country_code": "US",
"region_code": "US-CA",
"country": "United States",
"country_full": "United States",
"state": "California",
"city": "San Francisco",
"geographic_area": "San Francisco Bay Area",
"is_primary": true,
"is_headquarter": true
}
]
},
"app_url": "https://app.talktohumans.app/contacts"
}
],
"pagination": {
"limit": 10,
"has_more": false
}
}
}