curl --fail-with-body --max-time 30 "https://api.freshtalent.ai/v1/lists/hot" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY"
const listName = encodeURIComponent("hot");
const response = await fetch(`https://api.freshtalent.ai/v1/lists/${listName}`, {
signal: AbortSignal.timeout(30_000), headers: { Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { data } = await response.json();
for (const member of data.members) console.log(member.person_slug, member.stage);
import json
import os
from urllib.parse import quote
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists/" + quote("hot", safe=""),
headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
)
with urlopen(request, timeout=30) as response:
data = json.load(response)["data"]
print([(m["person_slug"], m["stage"]) for m in data["members"]])
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "hot",
"description": null,
"is_default": false,
"default_key": null,
"source_watch_id": null,
"member_count": 1,
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z",
"members": [
{
"id": "8c5f6a6b-5cb7-4e3f-a1fd-9aabf2d2c6e0",
"list_id": "550e8400-e29b-41d4-a716-446655440000",
"person_linkedin_url": "https://www.linkedin.com/in/derek-morrow",
"person_slug": "derek-morrow",
"person_full_name": "Derek Morrow",
"person_headline": null,
"person_picture_url": null,
"stage": "to-contact",
"notes": "",
"added_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
]
}
}
Get list
Retrieve list metadata and every membership in one response.
GET
/
lists
/
{id}
curl --fail-with-body --max-time 30 "https://api.freshtalent.ai/v1/lists/hot" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY"
const listName = encodeURIComponent("hot");
const response = await fetch(`https://api.freshtalent.ai/v1/lists/${listName}`, {
signal: AbortSignal.timeout(30_000), headers: { Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { data } = await response.json();
for (const member of data.members) console.log(member.person_slug, member.stage);
import json
import os
from urllib.parse import quote
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists/" + quote("hot", safe=""),
headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
)
with urlopen(request, timeout=30) as response:
data = json.load(response)["data"]
print([(m["person_slug"], m["stage"]) for m in data["members"]])
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "hot",
"description": null,
"is_default": false,
"default_key": null,
"source_watch_id": null,
"member_count": 1,
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z",
"members": [
{
"id": "8c5f6a6b-5cb7-4e3f-a1fd-9aabf2d2c6e0",
"list_id": "550e8400-e29b-41d4-a716-446655440000",
"person_linkedin_url": "https://www.linkedin.com/in/derek-morrow",
"person_slug": "derek-morrow",
"person_full_name": "Derek Morrow",
"person_headline": null,
"person_picture_url": null,
"stage": "to-contact",
"notes": "",
"added_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
]
}
}
Returns one list and all of its memberships for the authenticated organization. The path value is trimmed and resolves either an exact UUID or a case-insensitive list name. If a name matches more than one list, the Gateway chooses the most recently updated match, so use the UUID for stable references.
This endpoint has no pagination parameters.
Each member object is:
string
required
List UUID or case-insensitive name. The value must not be empty. UUIDs are the stable choice when names can change or collide.
data.members contains every member, ordered by updated_at descending. There is no meta.next; for the members-only route, use GET /lists/:id/members, which likewise returns all members with meta.count.
Response schema
data contains the list fields plus members:
| Field | Type | Nullability and meaning |
|---|---|---|
id | string (UUID) | Never null. |
name | string | Never null. |
description | string | Nullable. |
is_default | boolean | Whether the list is Gateway-managed. |
default_key | string | Nullable. |
source_watch_id | string (UUID) | Nullable. |
member_count | integer | Count of memberships. |
created_at, updated_at | string (ISO 8601 timestamp) | Never null. |
members | object[] | Never null; can be empty. |
| Field | Type | Nullability and meaning |
|---|---|---|
id, list_id | string (UUID) | Never null. |
person_linkedin_url | string | Never null; the membership upsert key. |
person_slug, person_full_name, person_headline, person_picture_url | string | Nullable enrichment fields. |
stage | string enum | One of to-contact, contacted, responded, passed. |
notes | string | Never null in API responses; an unset database value is normalized to "". |
added_at, updated_at | string (ISO 8601 timestamp) | Never null. |
{
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "hot",
"description": null,
"is_default": false,
"default_key": null,
"source_watch_id": null,
"member_count": 1,
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z",
"members": [
{
"id": "8c5f6a6b-5cb7-4e3f-a1fd-9aabf2d2c6e0",
"list_id": "550e8400-e29b-41d4-a716-446655440000",
"person_linkedin_url": "https://www.linkedin.com/in/derek-morrow",
"person_slug": "derek-morrow",
"person_full_name": "Derek Morrow",
"person_headline": null,
"person_picture_url": null,
"stage": "to-contact",
"notes": "",
"added_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
]
}
}
curl --fail-with-body --max-time 30 "https://api.freshtalent.ai/v1/lists/hot" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY"
const listName = encodeURIComponent("hot");
const response = await fetch(`https://api.freshtalent.ai/v1/lists/${listName}`, {
signal: AbortSignal.timeout(30_000), headers: { Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}` },
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { data } = await response.json();
for (const member of data.members) console.log(member.person_slug, member.stage);
import json
import os
from urllib.parse import quote
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists/" + quote("hot", safe=""),
headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
)
with urlopen(request, timeout=30) as response:
data = json.load(response)["data"]
print([(m["person_slug"], m["stage"]) for m in data["members"]])
Errors and recovery
400(invalid_request): when using the platform API key, provide a validX-FreshTalent-Org-IdUUID.401(unauthorized): provide a valid API key.402(payment_required): restore the organization’s entitlement.404(not_found): the UUID/name is not visible in this organization; check the identifier with List lists.429or5xx: retry with backoff. A successful read is safe to repeat.
Related
| Method | Path | Purpose |
|---|---|---|
GET | /lists/:id/members | Return memberships only, with meta.count. |
POST | /lists/:id/members | Add list members |
PATCH | /lists/:id/members/:membershipId | Update list member |
DELETE | /lists/:id | Delete list |
DELETE | /lists/:id/members/:membershipId | Remove one member; returns 204. |
:membershipId can be a membership UUID or a person slug when using the member routes.
Next: Add list members.