> ## Documentation Index
> Fetch the complete documentation index at: https://docs.freshtalent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update list member

> Partially update a list member's stage or notes.

Updates an existing membership without changing its person identity or list. The body is a partial object: omitted fields keep their current values. Send `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.

<ParamField path="id" type="string" required>
  List UUID or case-insensitive name.
</ParamField>

<ParamField path="membershipId" type="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.
</ParamField>

<ParamField body="stage" type="string">
  Optional enum: `to-contact`, `contacted`, `responded`, or `passed`. Omit to preserve the current stage.
</ParamField>

<ParamField body="notes" type="string">
  Optional string up to 2,000 characters. Omit to preserve notes; send `""` to clear them.
</ParamField>

The body may be `{}` 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

Returns `200` 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.

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "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"
    }
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"}'
  ```

  ```js JavaScript (native fetch) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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);
  ```

  ```python Python (stdlib) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"])
  ```
</RequestExample>

## Errors and recovery

* `400`: invalid stage, notes longer than 2,000 characters, a non-object body, an or a missing platform-key `X-FreshTalent-Org-Id` UUID. Fix the body/header.
* `401` (`unauthorized`) or `402` (`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](/api-reference/lists/get).
* `429` or `5xx`: retry with backoff. Repeating the same PATCH is safe for the same intended values, but reconcile with `GET /lists/{id}` if the response outcome is unknown.

This endpoint is not paginated and has no `next` link.

## Next steps

[Get list](/api-reference/lists/get) to inspect the updated member, or [Delete list](/api-reference/lists/delete) when the whole custom list is no longer needed.