> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/python/lists
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# client.lists

> Manage Lists, members and import operations with the Python SDK, including method signatures, parameters, return values, credit costs and errors.

- Last verified: 2026-11-04

Manage persistent Lists, their members and their import operations.

| Method | Endpoint | Cost |
| ------ | -------- | ---- |
| [`list()`](#list) | [GET /v2/lists](https://docs.reversecontact.com/endpoints/lists) | Free. |
| [`list_all()`](#list_all) | [GET /v2/lists](https://docs.reversecontact.com/endpoints/lists) | Free. |
| [`create()`](#create) | [POST /v2/lists](https://docs.reversecontact.com/endpoints/list-create) | Free. |
| [`retrieve()`](#retrieve) | [GET /v2/lists/{listId}](https://docs.reversecontact.com/endpoints/list) | Free. |
| [`delete()`](#delete) | [DELETE /v2/lists/{listId}](https://docs.reversecontact.com/endpoints/list-delete) | Free. |
| [`import_signals()`](#import_signals) | [POST /v2/lists/{listId}/intake/signals](https://docs.reversecontact.com/endpoints/list-intake-signals) | Free to queue. Each new member costs its identity price. Each data family you request costs its endpoint price, up to your maxCredits. |
| [`export()`](#export) | [GET /v2/lists/{listId}/export](https://docs.reversecontact.com/endpoints/list-export) | Free. |
| [`members.list()`](#memberslist) | [GET /v2/lists/{listId}/members](https://docs.reversecontact.com/endpoints/list-members) | Free. |
| [`members.list_all()`](#memberslist_all) | [GET /v2/lists/{listId}/members](https://docs.reversecontact.com/endpoints/list-members) | Free. |
| [`members.add()`](#membersadd) | [POST /v2/lists/{listId}/members](https://docs.reversecontact.com/endpoints/list-members-add) | Free to call. Each new person costs 1 credit from a Social profile URL (2 with live), 2 from an email or a name. Each new company costs 1 credit from a company page URL or a company id (2 when the page is read live), 2 from a domain. A member already on the List, or a Signal with no match, is free. |
| [`members.remove()`](#membersremove) | [DELETE /v2/lists/{listId}/members](https://docs.reversecontact.com/endpoints/list-members-remove) | Free. |
| [`operations.retrieve()`](#operationsretrieve) | [GET /v2/lists/{listId}/operations/{operationId}/progress](https://docs.reversecontact.com/endpoints/list-operation) | Free, even at a zero balance. Never counts toward rate limits. |
| [`operations.cancel()`](#operationscancel) | [POST /v2/lists/{listId}/operations/{operationId}/cancel](https://docs.reversecontact.com/endpoints/list-operation-cancel) | Free. Lines that had not started are never charged. |
| [`operations.wait()`](#operationswait) | [GET /v2/lists/{listId}/operations/{operationId}/progress](https://docs.reversecontact.com/endpoints/list-operation) | Free, even at a zero balance. Never counts toward rate limits. |

## Calling conventions

Examples assume `RC_API_KEY` is set. Replace example ids with ids returned by your own requests. Signatures show the published 0.3.0 synchronous methods. Use the same arguments with the [Python async client](https://docs.reversecontact.com/sdk/python/async-client).

`models` refers to `reversecontact.types`. `NOT_GIVEN` and `NotGiven` are the SDK's internal markers for omitted arguments. Leave these arguments out of your calls. For API body parameters, passing `None` sends an explicit null. Transport options use `None` to inherit their defaults. `Timeout` means a number of seconds or `httpx.Timeout`. Supply parameters marked **Required** to Python or to the API, even when the generated signature permits omission.

JSON response objects expose `data`, `quotas`, `metadata` and `http_response`. Check optional fields for `None`. See [First call](https://docs.reversecontact.com/sdk/python/first-call) for the response envelope. CSV methods return text and iterators yield items.

HTTP failures raise an `APIError` subclass based on the response: `BadRequestError`, `AuthenticationError`, `InsufficientCreditsError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `GoneError`, `UnprocessableEntityError`, `RateLimitError`, `DailyLimitError`, `KeyCreditLimitError`, `UnavailableForLegalReasonsError` or `InternalServerError`. See the [error mapping and retry rules](https://docs.reversecontact.com/sdk/python/errors-and-retries).

## list

Call [All Lists](https://docs.reversecontact.com/endpoints/lists) with `client.lists.list()`.

**Python SDK**

```python [Python SDK]
def list(
    *,
    per_page: int | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Page[models.ListListsItem]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `per_page` | `int \| NotGiven \| None` | Optional. Lists per page, from 1 to 200. Defaults to 200. |
| `cursor` | `str \| NotGiven \| None` | Optional. The `nextCursor` of the previous page. A malformed cursor, or one sent with other parameters, returns `400`. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Page[models.ListListsItem]`. A page with records in `data`, a `next_cursor`, `has_next_page()` and `get_next_page()`. The next-page method reuses the filters and returns `None` after the last page.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    page = client.lists.list(per_page=20)
    for item in page.data:
        if item is not None:
            print(item.to_dict())
```
## list_all

Call [All Lists](https://docs.reversecontact.com/endpoints/lists) with `client.lists.list_all()`.

**Python SDK**

```python [Python SDK]
def list_all(
    *,
    per_page: int | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    max_results: int | None = None,
    **extra: object,
) -> Iterator[models.ListListsItem | None]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `per_page` | `int \| NotGiven \| None` | Optional. Lists per page, from 1 to 200. Defaults to 200. |
| `cursor` | `str \| NotGiven \| None` | Optional. The `nextCursor` of the previous page. A malformed cursor, or one sent with other parameters, returns `400`. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `max_results` | `int \| None` | Optional. Maximum items yielded. `None` reads every page. `0` makes no request. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Iterator[models.ListListsItem | None]`. An iterator of typed records. Entries can be `None`. The iterator fetches pages only as you advance. Pagination is free. Omit `max_results` to read all pages.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options, invalid `max_results` or `per_page`, or a repeated pagination cursor. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    for item in client.lists.list_all(max_results=20):
        if item is not None:
            print(item.to_dict())
```
## create

Call [Create a List](https://docs.reversecontact.com/endpoints/list-create) with `client.lists.create()`.

**Python SDK**

```python [Python SDK]
def create(
    *,
    name: str | NotGiven | None = NOT_GIVEN,
    entity: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    idempotency_key: str | None = None,
    **extra: object,
) -> Result[models.CreateListData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `name` | `str \| NotGiven \| None` | **Required.** List name, 1 to 200 characters. Spaces around it are removed. |
| `entity` | `str \| NotGiven \| None` | **Required.** `persons` for people, `companies` for companies |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `idempotency_key` | `str \| None` | Optional. Key for this creation request. The SDK generates a key when omitted and reuses it on automatic retries. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.CreateListData]`. `data` contains the new List, including `id`, `name`, `entity` and member counts.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.create(name="Prospects", entity="persons")
    print(result.data if result is not None else None)
```
## retrieve

Call [Get a List](https://docs.reversecontact.com/endpoints/list) with `client.lists.retrieve()`.

**Python SDK**

```python [Python SDK]
def retrieve(
    list_id: str,
    *,
    per_page: int | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    kind: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.GetListData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID) |
| `per_page` | `int \| NotGiven \| None` | Optional. Rows per page, from 1 to 1,000. Defaults to 100. |
| `cursor` | `str \| NotGiven \| None` | Optional. The `nextCursor` of the previous page, sent with the same `kind`. A malformed cursor, or one sent with other parameters, returns `400`. |
| `kind` | `str \| NotGiven \| None` | Optional. `all` (default) mixes members and Pending Intake by added date, `members` or `pending` returns one kind only |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.GetListData]`. `data.list` contains List details. `data.members` contains one member page, and `data.next_cursor` holds its continuation cursor.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.retrieve("00000000-0000-4000-8000-000000000001")
    print(result.data if result is not None else None)
```
## delete

Call [Delete a List](https://docs.reversecontact.com/endpoints/list-delete) with `client.lists.delete()`.

**Python SDK**

```python [Python SDK]
def delete(
    list_id: str,
    *,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.DeleteListData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** Id (UUID) of the List to delete |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.DeleteListData]`. `data.deleted` indicates the deletion outcome.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.delete("00000000-0000-4000-8000-000000000001")
    print(result.data if result is not None else None)
```
## import_signals

Send `signals` or `source_url` according to the [import request rules](https://docs.reversecontact.com/endpoints/list-intake-signals). Save `operation_id` to resume a paused import.

**Python SDK**

```python [Python SDK]
def import_signals(
    list_id: str,
    *,
    signals: list[models.ImportListSignalsParamsSignalsItem | dict[str, object]] | NotGiven | None = NOT_GIVEN,
    source_url: str | NotGiven | None = NOT_GIVEN,
    live: bool | NotGiven | None = NOT_GIVEN,
    families: list[str] | NotGiven | None = NOT_GIVEN,
    max_credits: int | NotGiven | None = NOT_GIVEN,
    operation_id: str | NotGiven | None = NOT_GIVEN,
    webhook_url: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.ImportListSignalsData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID). |
| `signals` | `list[models.ImportListSignalsParamsSignalsItem \| dict[str, object]] \| NotGiven \| None` | **Required for the selected strategy.** 1 to 25,000 Signals, with the fields of [Add members](https://docs.reversecontact.com/endpoints/list-members-add#request-body), `externalId` included |
| `source_url` | `str \| NotGiven \| None` | **Required for the selected strategy.** A public HTTPS CSV file or Google Sheet URL instead of `signals`: up to 25,000 rows and 25 MiB. Columns are matched from their headers (Social URL, email, first name, last name, company, domain). |
| `live` | `bool \| NotGiven \| None` | Optional. `true` fetches the profile of each Social profile URL live. Omitted or `false`, saved data is used. No effect on a companies List. |
| `families` | `list[str] \| NotGiven \| None` | Optional. Data to buy for each member: `profile`, `company`, `contact_email`, `contact_phone`. A companies List takes `company` only. |
| `max_credits` | `int \| NotGiven \| None` | **Required for the selected strategy.** The most this operation may spend. Required with `families` when the worst case is above 25 credits. Omitted, the ceiling is the worst case of the import. |
| `operation_id` | `str \| NotGiven \| None` | Optional. Identifier for this import. The SDK generates a UUID when omitted. Reuse a stored id to resume the import. |
| `webhook_url` | `str \| NotGiven \| None` | Optional. Public HTTPS URL that receives a notification whenever the operation stops progressing. See [Webhook callback](https://docs.reversecontact.com/endpoints/list-intake-signals#webhook-callback) |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.ImportListSignalsData]`. `data.operation_id` identifies the import. The acknowledgement also exposes `poll_url`, `total_rows`, `duplicate_count` and `job`. Follow the import with `client.lists.operations.wait(list_id, operation_id)`. See [Lists and Bulk enrichment](https://docs.reversecontact.com/sdk/python/lists-and-bulk).

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.import_signals(
        "00000000-0000-4000-8000-000000000001",
        signals=[{"email": "jane@acme.com", "externalId": "crm-001"}],
        families=["contact_email"],
        max_credits=100,
    )
    print(result.data if result is not None else None)
```
## export

Call [Export a List](https://docs.reversecontact.com/endpoints/list-export) with `client.lists.export()`.

**Python SDK**

```python [Python SDK]
def export(
    list_id: str,
    *,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> str: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID) |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`str`. The List export as CSV text, ready to write to a UTF-8 file.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    csv_text = client.lists.export("00000000-0000-4000-8000-000000000001")
    print(csv_text)
```
## members.list

Call [List members](https://docs.reversecontact.com/endpoints/list-members) with `client.lists.members.list()`.

**Python SDK**

```python [Python SDK]
def list(
    list_id: str,
    *,
    per_page: int | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    kind: str | NotGiven | None = NOT_GIVEN,
    external_id: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Page[models.ListListMembersItem]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID) |
| `per_page` | `int \| NotGiven \| None` | Optional. Rows per page, from 1 to 1,000. Defaults to 100. |
| `cursor` | `str \| NotGiven \| None` | Optional. The `nextCursor` of the previous page, sent with the same filters. A malformed cursor, or one sent with other filters, returns `400`. |
| `kind` | `str \| NotGiven \| None` | Optional. `all` (default) mixes members and Pending Intake by added date, `members` or `pending` returns one kind only |
| `external_id` | `str \| NotGiven \| None` | Optional. Returns members with this identifier from your system (1 to 200 characters) |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Page[models.ListListMembersItem]`. A page with records in `data`, a `next_cursor`, `has_next_page()` and `get_next_page()`. The next-page method reuses the filters and returns `None` after the last page.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    page = client.lists.members.list("00000000-0000-4000-8000-000000000001", per_page=20)
    for item in page.data:
        if item is not None:
            print(item.to_dict())
```
## members.list_all

Call [List members](https://docs.reversecontact.com/endpoints/list-members) with `client.lists.members.list_all()`.

**Python SDK**

```python [Python SDK]
def list_all(
    list_id: str,
    *,
    per_page: int | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    kind: str | NotGiven | None = NOT_GIVEN,
    external_id: str | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    max_results: int | None = None,
    **extra: object,
) -> Iterator[models.ListListMembersItem | None]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID) |
| `per_page` | `int \| NotGiven \| None` | Optional. Rows per page, from 1 to 1,000. Defaults to 100. |
| `cursor` | `str \| NotGiven \| None` | Optional. The `nextCursor` of the previous page, sent with the same filters. A malformed cursor, or one sent with other filters, returns `400`. |
| `kind` | `str \| NotGiven \| None` | Optional. `all` (default) mixes members and Pending Intake by added date, `members` or `pending` returns one kind only |
| `external_id` | `str \| NotGiven \| None` | Optional. Returns members with this identifier from your system (1 to 200 characters) |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `max_results` | `int \| None` | Optional. Maximum items yielded. `None` reads every page. `0` makes no request. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Iterator[models.ListListMembersItem | None]`. An iterator of typed records. Entries can be `None`. The iterator fetches pages only as you advance. Pagination is free. Omit `max_results` to read all pages.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options, invalid `max_results` or `per_page`, or a repeated pagination cursor. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    for item in client.lists.members.list_all("00000000-0000-4000-8000-000000000001", max_results=20):
        if item is not None:
            print(item.to_dict())
```
## members.add

Call [Add members](https://docs.reversecontact.com/endpoints/list-members-add) with `client.lists.members.add()`.

**Python SDK**

```python [Python SDK]
def add(
    list_id: str,
    *,
    signals: list[models.AddListMembersParamsSignalsItem | dict[str, object]] | NotGiven | None = NOT_GIVEN,
    source: str | NotGiven | None = NOT_GIVEN,
    live: bool | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.AddListMembersData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID). |
| `signals` | `list[models.AddListMembersParamsSignalsItem \| dict[str, object]] \| NotGiven \| None` | **Required.** 1 to 1,000 Signals, described below |
| `source` | `str \| NotGiven \| None` | Optional. `paste` (default) or `file`: how the Pending Intake line was added |
| `live` | `bool \| NotGiven \| None` | Optional. `true` fetches the profile of a Social profile URL live (2 credits). Omitted or `false`, saved data is used (1 credit). No effect on a companies List. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.AddListMembersData]`. `data` reports `inserted`, `skipped`, `refused`, `unresolved_count`, `stopped_reason`, `credits_consumed` and per-signal `results`.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.members.add(
        "00000000-0000-4000-8000-000000000001",
        signals=[{"email": "jane@acme.com", "externalId": "crm-001"}],
    )
    print(result.data if result is not None else None)
```
## members.remove

Provide at least one id in `member_ids` or `pending_ids`, with at most 25,000 ids combined.

**Python SDK**

```python [Python SDK]
def remove(
    list_id: str,
    *,
    member_ids: list[str] | NotGiven | None = NOT_GIVEN,
    pending_ids: list[str] | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.RemoveListMembersData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID). |
| `member_ids` | `list[str] \| NotGiven \| None` | **Required for the selected strategy.** Member ids (UUID) to remove, the `id` of rows with `kind: "member"` |
| `pending_ids` | `list[str] \| NotGiven \| None` | **Required for the selected strategy.** Pending Intake ids (UUID) to dismiss, the `id` of rows with `kind: "pending"` |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.RemoveListMembersData]`. `data.removed` counts removed members. `data.dismissed` counts dismissed Pending Intake lines.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.members.remove(
        "00000000-0000-4000-8000-000000000001",
        member_ids=["00000000-0000-4000-8000-000000000002"],
    )
    print(result.data if result is not None else None)
```
## operations.retrieve

Call [Read a List operation](https://docs.reversecontact.com/endpoints/list-operation) with `client.lists.operations.retrieve()`.

**Python SDK**

```python [Python SDK]
def retrieve(
    list_id: str,
    operation_id: str,
    *,
    wait: int | NotGiven | None = NOT_GIVEN,
    rows: str | NotGiven | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    per_page: int | NotGiven | None = NOT_GIVEN,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.GetListOperationData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID) |
| `operation_id` | `str` | **Required.** The `operation_id` of the import acknowledgement |
| `wait` | `int \| NotGiven \| None` | Optional. Hold the request up to this many seconds, 0 to 20, while the operation runs. It answers as soon as the operation settles, pauses or stops, or with the operation still running when the wait ends. Defaults to 0. |
| `rows` | `str \| NotGiven \| None` | Optional. `true` adds one page of per-line results |
| `cursor` | `str \| NotGiven \| None` | Optional. With `rows=true`: the `rows.nextCursor` of the previous page |
| `per_page` | `int \| NotGiven \| None` | Optional. With `rows=true`: lines per page, from 1 to 1,000. Defaults to 200. |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.GetListOperationData]`. `data` contains operation progress, `client_action`, `next_step`, credits and optional `rows`. This reads one state without waiting for the import to finish.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options or a `wait` outside the integer range 0 to 20. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.operations.retrieve(
        "00000000-0000-4000-8000-000000000001",
        "00000000-0000-4000-8000-000000000002",
        wait=20, rows="true",
    )
    print(result.data if result is not None else None)
```
## operations.cancel

Call [Cancel a List operation](https://docs.reversecontact.com/endpoints/list-operation-cancel) with `client.lists.operations.cancel()`.

**Python SDK**

```python [Python SDK]
def cancel(
    list_id: str,
    operation_id: str,
    *,
    timeout: Timeout | None = None,
    max_retries: int | None = None,
    headers: Mapping[str, str] | None = None,
    **extra: object,
) -> Result[models.CancelListOperationData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID) |
| `operation_id` | `str` | **Required.** The `operation_id` of the import acknowledgement |
| `timeout` | `Timeout \| None` | Optional. Seconds per HTTP attempt, or `httpx.Timeout`. Uses the client setting when `None`. |
| `max_retries` | `int \| None` | Optional. Retries after the first HTTP attempt. Uses the client setting when `None`. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |
| `**extra` | `object` | Optional. Additional API keyword arguments, including camelCase aliases, passed through to the API. |

**Returns**

`Result[models.CancelListOperationData]`. `data` is the operation state after the cancellation request. Inspect `status` and `client_action`.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid SDK options. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.operations.cancel(
        "00000000-0000-4000-8000-000000000001",
        "00000000-0000-4000-8000-000000000002",
    )
    print(result.data if result is not None else None)
```
## operations.wait

Call [Read a List operation](https://docs.reversecontact.com/endpoints/list-operation) with `client.lists.operations.wait()`.

**Python SDK**

```python [Python SDK]
def wait(
    list_id: str,
    operation_id: str,
    *,
    timeout: float = 1800,
    poll_wait: int = 20,
    on_poll: Callable[[Result[GetListOperationData]], None] | None = None,
    headers: Mapping[str, str] | None = None,
) -> Result[GetListOperationData]: ...
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `list_id` | `str` | **Required.** List id (UUID) |
| `operation_id` | `str` | **Required.** The `operation_id` of the import acknowledgement |
| `timeout` | `float` | Optional. Overall polling deadline in seconds. Default `1800`. |
| `poll_wait` | `int` | Optional. Long-poll duration from `0` to `20` seconds. Default `20`. |
| `on_poll` | `Callable[[Result[GetListOperationData]], None] \| None` | Optional. Synchronous callback called with each successful poll response. |
| `headers` | `Mapping[str, str] \| None` | Optional. Additional HTTP headers for this call. |

**Returns**

`Result[GetListOperationData]`. `data` is the operation state when `client_action` is no longer `poll`, such as `done`, `resume` or `reconcile`. Inspect `next_step`. Failed or paused operations are returned without `JobFailedError`.

**Errors**

`APIError` subclasses follow the HTTP mapping above. `APIConnectionError` reports transport failures. `APITimeoutError` reports timed-out attempts. `ReverseContactError` covers invalid `poll_wait` or `timeout`. `JobTimeoutError` reports an expired deadline. Failed or paused server states are returned for inspection. Malformed typed response data can raise Pydantic `ValidationError`.

**Example**

**Python SDK**

```python [Python SDK]
from reversecontact import ReverseContact

with ReverseContact() as client:
    result = client.lists.operations.wait(
        "00000000-0000-4000-8000-000000000001",
        "00000000-0000-4000-8000-000000000002",
    )
    print(result.data if result is not None else None)
```
## Related guides

See the [Python SDK overview](https://docs.reversecontact.com/sdk/python), [Lists and bulk](https://docs.reversecontact.com/sdk/python/lists-and-bulk) and [Bulk](https://docs.reversecontact.com/sdk/python/bulk).

## FAQ

### How do I read every member of a List in Python?

Use `client.lists.members.list_all(list_id)`. The free iterator follows every page unless you set an optional `max_results` cap.

### How do I follow a List import in Python?

Save the `operation_id` returned by `client.lists.import_signals()` and call `client.lists.operations.wait(list_id, operation_id)`. Inspect `client_action` and `next_step`.

### Does lists.operations.wait raise on a paused import?

`client.lists.operations.wait()` returns when `client_action` stops being `poll`, including paused or failed states. If the wait exceeds its deadline, the SDK raises `JobTimeoutError`.

### What does lists.export return in Python?

`client.lists.export(list_id)` returns the List export as CSV text, ready to write to a UTF-8 file.