curl --fail-with-body --max-time 30 -X POST "https://api.freshtalent.ai/v1/lists" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"hot","description":"Palantir leavers to contact"}'
const response = await fetch("https://api.freshtalent.ai/v1/lists", {
method: "POST",
signal: AbortSignal.timeout(30_000),
headers: {
Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "hot", description: "Palantir leavers to contact" }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { data: list } = await response.json();
console.log(list.id);
import json
import os
from urllib.request import Request, urlopen
payload = json.dumps({"name": "hot", "description": "Palantir leavers to contact"}).encode()
request = Request(
"https://api.freshtalent.ai/v1/lists",
data=payload,
method="POST",
headers={
"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}",
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=30) as response:
list_ = json.load(response)["data"]
print(list_["id"])
{
"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"
}
}
Create list
Create a custom organization-scoped list with no members.
POST
/
lists
curl --fail-with-body --max-time 30 -X POST "https://api.freshtalent.ai/v1/lists" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"hot","description":"Palantir leavers to contact"}'
const response = await fetch("https://api.freshtalent.ai/v1/lists", {
method: "POST",
signal: AbortSignal.timeout(30_000),
headers: {
Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "hot", description: "Palantir leavers to contact" }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { data: list } = await response.json();
console.log(list.id);
import json
import os
from urllib.request import Request, urlopen
payload = json.dumps({"name": "hot", "description": "Palantir leavers to contact"}).encode()
request = Request(
"https://api.freshtalent.ai/v1/lists",
data=payload,
method="POST",
headers={
"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}",
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=30) as response:
list_ = json.load(response)["data"]
print(list_["id"])
{
"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"
}
}
Creates a custom list for the authenticated organization. The Gateway inserts a new row and returns it with
The JSON body is an object with only
member_count: 0, is_default: false, and null generated-list references. This endpoint does not add members and does not provide an idempotency key or upsert mode.
string
required
List name. Must contain 1–80 characters. The Gateway trims surrounding whitespace before storing it. Names are not enforced as unique by this route or its database insert.
string
Optional description, up to 400 characters. Omit it for
null; an empty string is stored as null after trimming. Send a string when setting it. The current framework can coerce null to an empty string; do not use coercion as your client contract.name and description; unknown top-level fields are stripped by the framework.
Response schema
data is a list object with the fields below. Timestamps are ISO 8601 strings.
| Field | Type | Nullability and meaning |
|---|---|---|
id | string (UUID) | Never null; use it for stable later references. |
name | string | Never null. |
description | string | null when omitted or blank after trimming. |
is_default | boolean | Always false for a list created here. |
default_key | string | Always null for a list created here. |
source_watch_id | string (UUID) | Always null for a list created here. |
member_count | integer | Always 0 in this response. |
created_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": 0,
"created_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
}
curl --fail-with-body --max-time 30 -X POST "https://api.freshtalent.ai/v1/lists" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"hot","description":"Palantir leavers to contact"}'
const response = await fetch("https://api.freshtalent.ai/v1/lists", {
method: "POST",
signal: AbortSignal.timeout(30_000),
headers: {
Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ name: "hot", description: "Palantir leavers to contact" }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
const { data: list } = await response.json();
console.log(list.id);
import json
import os
from urllib.request import Request, urlopen
payload = json.dumps({"name": "hot", "description": "Palantir leavers to contact"}).encode()
request = Request(
"https://api.freshtalent.ai/v1/lists",
data=payload,
method="POST",
headers={
"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}",
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=30) as response:
list_ = json.load(response)["data"]
print(list_["id"])
Errors, side effects, and retry safety
400: request-schema failure, such as a missing name, a name longer than 80 characters, a description longer than 400 characters, or a missing platform-keyX-FreshTalent-Org-IdUUID. Fix the body/header before retrying.401(unauthorized): provide a valid API key.402(payment_required): restore the organization’s entitlement before retrying.429: back off and retry only after considering whether the first request may have succeeded.5xx: the outcome may be unknown. This POST is not idempotent; a retry can create another list, because the route always inserts and does not enforce name uniqueness. Reconcile withGET /listsand use the returned UUIDs before retrying.
201 has no pagination metadata and no next link. Add people separately with Add list members.