curl --fail-with-body --max-time 30 -X PATCH "https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage":"contacted","notes":"Reached out on LinkedIn"}'
const response = await fetch("https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow", {
method: "PATCH",
signal: AbortSignal.timeout(30_000),
headers: {
Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ stage: "contacted", notes: "Reached out on LinkedIn" }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log((await response.json()).data);
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow",
data=json.dumps({"stage": "contacted", "notes": "Reached out on LinkedIn"}).encode(),
method="PATCH",
headers={
"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}",
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=30) as response:
print(json.load(response)["data"])
{
"data": {
"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": "contacted",
"notes": "Reached out on LinkedIn",
"added_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
}
Update list member
Partially update a list member’s stage or notes.
PATCH
/
lists
/
{id}
/
members
/
{membershipId}
curl --fail-with-body --max-time 30 -X PATCH "https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage":"contacted","notes":"Reached out on LinkedIn"}'
const response = await fetch("https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow", {
method: "PATCH",
signal: AbortSignal.timeout(30_000),
headers: {
Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ stage: "contacted", notes: "Reached out on LinkedIn" }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log((await response.json()).data);
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow",
data=json.dumps({"stage": "contacted", "notes": "Reached out on LinkedIn"}).encode(),
method="PATCH",
headers={
"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}",
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=30) as response:
print(json.load(response)["data"])
{
"data": {
"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": "contacted",
"notes": "Reached out on LinkedIn",
"added_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
}
Updates an existing membership without changing its person identity or list. The body is a partial object: omitted fields keep their current values. Send
The body may be
notes: "" to clear notes. Do not send null: the current framework can coerce it to an empty string, which also clears notes rather than preserving them.
string
required
List UUID or case-insensitive name.
string
required
Membership UUID or the member’s person slug. A slug is resolved within the addressed list. For a UUID, the current Gateway updater scopes the lookup to the organization but does not re-check that the UUID’s
list_id matches the path list; use a UUID from the addressed list and treat the path/UUID pair as a client responsibility.string
Optional enum:
to-contact, contacted, responded, or passed. Omit to preserve the current stage.string
Optional string up to 2,000 characters. Omit to preserve notes; send
"" to clear them.{} because neither property is required. Unknown properties are stripped by the framework. A successful update refreshes updated_at, even if no field value changes.
Response schema
Returns200 with data as one membership object: id and list_id UUIDs; required person_linkedin_url; nullable person enrichment fields; stage enum; non-null string notes; and ISO added_at/updated_at timestamps.
{
"data": {
"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": "contacted",
"notes": "Reached out on LinkedIn",
"added_at": "2026-09-07T10:00:00.000Z",
"updated_at": "2026-09-07T10:00:00.000Z"
}
}
curl --fail-with-body --max-time 30 -X PATCH "https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow" \
-H "Authorization: Bearer $FRESHTALENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"stage":"contacted","notes":"Reached out on LinkedIn"}'
const response = await fetch("https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow", {
method: "PATCH",
signal: AbortSignal.timeout(30_000),
headers: {
Authorization: `Bearer ${process.env.FRESHTALENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ stage: "contacted", notes: "Reached out on LinkedIn" }),
});
if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
console.log((await response.json()).data);
import json
import os
from urllib.request import Request, urlopen
request = Request(
"https://api.freshtalent.ai/v1/lists/hot/members/derek-morrow",
data=json.dumps({"stage": "contacted", "notes": "Reached out on LinkedIn"}).encode(),
method="PATCH",
headers={
"Authorization": f"Bearer {os.environ['FRESHTALENT_API_KEY']}",
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=30) as response:
print(json.load(response)["data"])
Errors and recovery
400: invalid stage, notes longer than 2,000 characters, a non-object body, an or a missing platform-keyX-FreshTalent-Org-IdUUID. Fix the body/header.401(unauthorized) or402(payment_required): fix authentication or entitlement.404(not_found): the list or membership was not found in the organization; check the UUID/slug with Get list.429or5xx: retry with backoff. Repeating the same PATCH is safe for the same intended values, but reconcile withGET /lists/{id}if the response outcome is unknown.
next link.