curl --fail-with-body --max-time 30 "https://api.freshtalent.ai/v1/lists" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY"
const response = await fetch("https://api.freshtalent.ai/v1/lists", {
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 body = await response.json();
console.log(body.data, body.meta.count);
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists",
headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
)
with urlopen(request, timeout=30) as response:
body = json.load(response)
print(body["data"], body["meta"]["count"])
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "hot",
"description": null,
"is_default": false,
"default_key": null,
"source_watch_id": null,
"member_count": 0,
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
],
"meta": {
"count": 1
}
}
List lists
Return every list visible to the authenticated organization, including generated default lists.
GET
/
lists
curl --fail-with-body --max-time 30 "https://api.freshtalent.ai/v1/lists" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY"
const response = await fetch("https://api.freshtalent.ai/v1/lists", {
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 body = await response.json();
console.log(body.data, body.meta.count);
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists",
headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
)
with urlopen(request, timeout=30) as response:
body = json.load(response)
print(body["data"], body["meta"]["count"])
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "hot",
"description": null,
"is_default": false,
"default_key": null,
"source_watch_id": null,
"member_count": 0,
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
],
"meta": {
"count": 1
}
}
Returns all lists for the API-key’s organization. The Gateway calls its default-list synchronizer before reading, so generated origin/Target lists and their current member counts can be materialized or refreshed as part of this request. A list
Next: Create list or Get list.
id is a UUID; other list routes also accept a case-insensitive list name.
This endpoint has no query parameters and is not paginated. It returns every list in data, ordered with default lists first and then by the Gateway’s stable default-list ordering. meta.next is never returned.
No
limit parameter is supported. The endpoint returns all lists.Response schema
data is an array of list objects:
| Field | Type | Nullability and meaning |
|---|---|---|
id | string (UUID) | Never null. |
name | string | Never null. |
description | string | null when no description is stored. |
is_default | boolean | true for Gateway-managed origin/Target lists. |
default_key | string | null for custom lists; a generated-list key when present. |
source_watch_id | string (UUID) | null when the list is not sourced from a Target/watch. |
member_count | integer | Count of memberships in this list, including zero. |
created_at, updated_at | string (ISO 8601 timestamp) | Never null. |
meta.count is the number of objects in data. There is no cursor, offset, page size, or next URL.
{
"data": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "hot",
"description": null,
"is_default": false,
"default_key": null,
"source_watch_id": null,
"member_count": 0,
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
],
"meta": {
"count": 1
}
}
curl --fail-with-body --max-time 30 "https://api.freshtalent.ai/v1/lists" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY"
const response = await fetch("https://api.freshtalent.ai/v1/lists", {
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 body = await response.json();
console.log(body.data, body.meta.count);
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists",
headers={"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}"},
)
with urlopen(request, timeout=30) as response:
body = json.load(response)
print(body["data"], body["meta"]["count"])
Errors and recovery
400(invalid_request): when using the platform API key, provide a validX-FreshTalent-Org-IdUUID.401(unauthorized): provide a validAuthorization: Bearer ...API key.402(payment_required): the organization’s trial or paid access is locked; restore entitlement and retry.429: respect the rate limit and retry with backoff.500or another5xx: the read may have failed while default lists were being synchronized; retry with backoff, then reconcile with a freshGET /lists.
200 is safe to retry. Because this read can refresh generated lists, a caller should not treat the request as a completely side-effect-free database read.
Related
| Method | Path | Purpose |
|---|---|---|
POST | /lists | Create list |
GET | /lists/:id | Get list |
DELETE | /lists/:id | Delete list |