---
title: "Reassign List Owner"
method: PATCH
path: "/lists/{audience_id}/owner"
tags: ["Lists"]
---

# Reassign List Owner

`PATCH /lists/{audience_id}/owner`

## Request

- Base URL: `https://be.graph8.com/api/v1`
- URL: `https://be.graph8.com/api/v1/lists/{audience_id}/owner`
- Auth: HTTP bearer

Hand a list to someone else.

`mode="list_and_records"` ALSO re-owns every record in the list. Under
record-level scoping that changes who can see them, so preview it first.

This route carries no `verify_list_access_dep` in the app - the transfer
rules are enforced inside the handler instead, and they are stricter than
the per-list read gate rather than weaker.

## Path parameters

- `audience_id` integer, required: List (audience) id.

## Headers

- `Authorization` string, nullable
- `X-Target-Org-Id` string, nullable

## Request body

- ReassignListOwnerRequest: Hand a list to someone else. `mode` decides how far the transfer reaches, and the difference is not cosmetic: `list_and_records` re-owns every CONTACT in the list as well, which changes who can see them under record-level scoping. Preview it first with `GET /lists/{id}/owner/preview`.
  - `owner_user_id` string, required
  - `owner_email` string, email, required: Must agree with the user id - the app verifies both. Typed as an email at the request layer because the app's model is `EmailStr` and is built inside the handler: a malformed address would otherwise raise there and escape as a 500 rather than a 422.
  - `mode` 'list_only' | 'list_and_records': `list_only` moves just the list. `list_and_records` also re-owns every record in it, which can change who else can see them.

## Response `200`

Successful Response

- ApiResponseListPayload
  - `data` ListPayload, required: An open envelope for a list, a capability map or a job result. Open because several of these return the whole `Audience`, whose shape carries per-source metadata that differs between an uploaded file, a dynamic query and a master list - and grows with them.
  - `pagination` PaginationMeta
    - `page` integer, required: Current page number (1-indexed)
    - `limit` integer, required: Items per page
    - `total` integer, required: Total number of items
    - `has_next` boolean, required: Whether there are more pages
    - `next_cursor` string, nullable: Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers.
    - `total_available` integer, nullable: Search endpoints only: how many records really match, when known. Can be larger than `total`, which is capped at the 10,000 results that can be paged. For company search this is a distinct-company estimate. Null when unknown; absent outside search.
    - `total_is_lower_bound` boolean, nullable: Search endpoints only: true when more records match than `total` shows (the result set is larger than the 10,000 results that can be paged). Absent outside search.
    - `notes` string[], nullable: Search endpoints only: plain-language notes about the result, e.g. that more records match than can be paged, or that a reversed `between` range was put in order.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/graph8/apis/graph8-developer-api.md) · [All operations](https://skmtc.dev/graph8/apis/graph8-developer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/graph8/apis/graph8-developer-api/revisions/2e7cfa0ca921?raw)