# CRM API — Lists

> Canonical URL: https://developers.apideck.com/apis/crm/reference#tag/Lists

This document contains every operation on the `Lists` resource.

---

# List lists

> **CRM API** · `GET /crm/lists`
> Canonical URL: https://developers.apideck.com/apis/crm/reference#tag/Lists/operation/listsAll
> MCP tool: `crm-lists-all`

## Authentication

- Send `Authorization: Bearer $API_KEY` using your Apideck secret API key. Keep the key server-side; never put it in a URL or client-side code.

Use the application, consumer and connector headers listed in Parameters below for this operation.

## Learn more

- [How does cursor pagination work?](https://developers.apideck.com/glossary#cursor)

List lists

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `raw` | query | `boolean` | No | Include raw response. Mostly used for debugging purposes |
| `x-apideck-consumer-id` | header | `string` | Yes | ID of the consumer which you want to get or push data from |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `x-apideck-service-id` | header | `string` | No | Provide the service id you want to call (e.g., pipedrive). Only needed when a consumer has activated multiple integrations for a Unified API. |
| `cursor` | query | `string` | No | Cursor to start from. You can find cursors for next/previous pages in the meta.cursors property of the response. |
| `limit` | query | `integer` | No | Number of results to return. Minimum 1, Maximum 200, Default 20 |
| `pass_through` | query | `object` | No | Optional unmapped key/values that will be passed through to downstream as query parameters. Ie: ?pass_through[search]=leads becomes ?search=leads |
| `fields` | query | `string` | No | The 'fields' parameter allows API users to specify the fields they want to include in the API response. If this parameter is not present, the API will return all available fields. If this parameter is present, only the fields specified in the comma-separated string will be included in the response. Nested properties can also be requested by using a dot notation. <br /><br />Example: `fields=name,email,addresses.city`<br /><br />In the example above, the response will only include the fields "name", "email" and "addresses.city". If any other fields are available, they will be excluded. |

### Responses

#### 200 — Lists

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `service` `string` **required** — Apideck ID of service provider — example: `hubspot`
- `resource` `string` **required** — Unified API resource name — example: `lists`
- `operation` `string` **required** — Operation performed — example: `all`
- `data` `array of object` **required**
  - `id` `string` **required** — The unique identifier of the List. — example: `12345`
  - `name` `string` **required** — The name of the List. — example: `Newsletter Subscribers`
  - `description` `string` — The description of the List. — example: `Contacts who opted in to the monthly newsletter.`
  - `type` `string` — Whether the List is static (a fixed set of records) or dynamic (a saved segment that is automatically kept up to date based on filter criteria). — enum: `static`, `dynamic` — example: `dynamic`
  - `visibility` `string` — The visibility of the List. Which of these values a given connector can return depends on its native sharing model — see the connector-specific gotchas below for details. — enum: `private`, `shared`, `public` — example: `shared`
  - `owner_id` `string` — The unique identifier of the user who owns the List. — example: `12345`
  - `filter_criteria` `object` — The filter criteria used to determine which records belong to a dynamic List. Shape is connector-native and passed through largely as-is (e.g. Close returns its own nested query-tree structure) rather than normalized to a common format.
  - `record_count` `integer` — The number of records currently in the List. — example: `42`
  - `folder_id` `string` — The unique identifier of the folder the List is organized under. — example: `12345`
  - `object_type` `string` — The type of CRM records the List contains. Normalized to a lowercase plural noun for the vendor's standard object types (e.g. contacts, companies, opportunities, leads, tickets, campaigns, tasks, events); for vendor-specific or custom object types the raw downstream identifier is passed through unchanged, following the connector's native casing (e.g. a HubSpot custom objectTypeId like 2-12345 or a Salesforce custom object API name), so a raw value may not always be distinguishable from a normalized one. This field is intentionally open-ended — no closed enum is enforced. — example: `contacts`
  - `is_dynamic` `boolean` — Whether the List is dynamic, meaning its records are automatically kept up to date based on filter criteria. This is a boolean mirror of `type` (`true` when `type` is `dynamic`, `false` when `static`), provided for callers that prefer a boolean check over a string comparison. — example: `true`
  - `is_favorite` `boolean` — Whether the List has been marked as a favorite. — example: `false`
  - `is_default` `boolean` — Whether the List is a default List. — example: `false`
  - `is_system` `boolean` — Whether the List is a system-generated List. — example: `false`
  - `custom_fields` `array of object`
    - `id` `string` — Unique identifier for the custom field. — example: `2389328923893298`
    - `name` `string` — Name of the custom field. — example: `employee_level`
    - `ref_name` `string` — Display name of the record a reference-type custom field points at. `value` carries that record's id; this carries its human-readable name, so a consumer does not need a second lookup to render it. — example: `Marketing`
    - `description` `string` — More information about the custom field — example: `Employee Level`
    - `value` `string | number | boolean | object | array of string | number | boolean | object`
      - One of:
        - Option 1: string
        - Option 2: number
        - Option 3: boolean
        - Option 4: object

        - Option 5: array of string | number | boolean | object
  - `tags` `array of string`
  - `updated_by` `string` — The unique identifier of the user who last updated the List. — example: `12345`
  - `created_by` `string` — The unique identifier of the user who created the List. — example: `12345`
  - `updated_at` `string` — The date and time when the List was last updated. — format: `date-time` — example: `2020-09-30T07:43:32.000Z`
  - `created_at` `string` — The date and time when the List was created. — format: `date-time` — example: `2020-09-30T07:43:32.000Z`
- `_raw` `object` — Raw response from the integration when raw=true query param is provided
- `meta` `object` — Response metadata
  - `items_on_page` `integer` — Number of items returned in the data property of the response — example: `50`
  - `cursors` `object` — Cursors to navigate to previous or next pages through the API
    - `previous` `string` — Cursor to navigate to the previous page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjE=`
    - `current` `string` — Cursor to navigate to the current page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjI=`
    - `next` `string` — Cursor to navigate to the next page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjM=`
  - `total_count` `integer` — Number of records available in total for this resource — example: `1`
  - `warnings` `array of object` — Non-fatal warnings emitted when optional workflow steps failed. Present only when at least one step degraded; the response status remains 200.
    - `type` `string` — Discriminator for the warning kind. — example: `downstream_request_failed`
    - `status_code` `integer` — HTTP status code returned by the failed downstream request, when available. — example: `429`
    - `error` `string` — Short error description from the downstream provider, when available.
    - `operation` `string` — Identifier of the workflow step that failed. — example: `getManager`
    - `message` `string` — Detailed message from the downstream provider, when available.
- `links` `object` — Links to navigate to previous or next pages through the API
  - `previous` `string` — Link to navigate to the previous page through the API — example: `https://unify.apideck.com/crm/companies?cursor=em9oby1jcm06OnBhZ2U6OjE%3D`
  - `current` `string` — Link to navigate to the current page through the API — example: `https://unify.apideck.com/crm/companies`
  - `next` `string` — Link to navigate to the previous page through the API — example: `https://unify.apideck.com/crm/companies?cursor=em9oby1jcm06OnBhZ2U6OjM`

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---

# Get list

> **CRM API** · `GET /crm/lists/{id}`
> Canonical URL: https://developers.apideck.com/apis/crm/reference#tag/Lists/operation/listsOne
> MCP tool: `crm-lists-one`

## Authentication

- Send `Authorization: Bearer $API_KEY` using your Apideck secret API key. Keep the key server-side; never put it in a URL or client-side code.

Use the application, consumer and connector headers listed in Parameters below for this operation.

Get list

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | `string` | Yes | ID of the record you are acting upon. |
| `x-apideck-consumer-id` | header | `string` | Yes | ID of the consumer which you want to get or push data from |
| `x-apideck-app-id` | header | `string` | Yes | The ID of your Unify application |
| `x-apideck-service-id` | header | `string` | No | Provide the service id you want to call (e.g., pipedrive). Only needed when a consumer has activated multiple integrations for a Unified API. |
| `raw` | query | `boolean` | No | Include raw response. Mostly used for debugging purposes |
| `fields` | query | `string` | No | The 'fields' parameter allows API users to specify the fields they want to include in the API response. If this parameter is not present, the API will return all available fields. If this parameter is present, only the fields specified in the comma-separated string will be included in the response. Nested properties can also be requested by using a dot notation. <br /><br />Example: `fields=name,email,addresses.city`<br /><br />In the example above, the response will only include the fields "name", "email" and "addresses.city". If any other fields are available, they will be excluded. |

### Responses

#### 200 — List

- `status_code` `integer` **required** — HTTP Response Status Code — example: `200`
- `status` `string` **required** — HTTP Response Status — example: `OK`
- `service` `string` **required** — Apideck ID of service provider — example: `hubspot`
- `resource` `string` **required** — Unified API resource name — example: `lists`
- `operation` `string` **required** — Operation performed — example: `one`
- `data` `object` **required**
  - `id` `string` **required** — The unique identifier of the List. — example: `12345`
  - `name` `string` **required** — The name of the List. — example: `Newsletter Subscribers`
  - `description` `string` — The description of the List. — example: `Contacts who opted in to the monthly newsletter.`
  - `type` `string` — Whether the List is static (a fixed set of records) or dynamic (a saved segment that is automatically kept up to date based on filter criteria). — enum: `static`, `dynamic` — example: `dynamic`
  - `visibility` `string` — The visibility of the List. Which of these values a given connector can return depends on its native sharing model — see the connector-specific gotchas below for details. — enum: `private`, `shared`, `public` — example: `shared`
  - `owner_id` `string` — The unique identifier of the user who owns the List. — example: `12345`
  - `filter_criteria` `object` — The filter criteria used to determine which records belong to a dynamic List. Shape is connector-native and passed through largely as-is (e.g. Close returns its own nested query-tree structure) rather than normalized to a common format.
  - `record_count` `integer` — The number of records currently in the List. — example: `42`
  - `folder_id` `string` — The unique identifier of the folder the List is organized under. — example: `12345`
  - `object_type` `string` — The type of CRM records the List contains. Normalized to a lowercase plural noun for the vendor's standard object types (e.g. contacts, companies, opportunities, leads, tickets, campaigns, tasks, events); for vendor-specific or custom object types the raw downstream identifier is passed through unchanged, following the connector's native casing (e.g. a HubSpot custom objectTypeId like 2-12345 or a Salesforce custom object API name), so a raw value may not always be distinguishable from a normalized one. This field is intentionally open-ended — no closed enum is enforced. — example: `contacts`
  - `is_dynamic` `boolean` — Whether the List is dynamic, meaning its records are automatically kept up to date based on filter criteria. This is a boolean mirror of `type` (`true` when `type` is `dynamic`, `false` when `static`), provided for callers that prefer a boolean check over a string comparison. — example: `true`
  - `is_favorite` `boolean` — Whether the List has been marked as a favorite. — example: `false`
  - `is_default` `boolean` — Whether the List is a default List. — example: `false`
  - `is_system` `boolean` — Whether the List is a system-generated List. — example: `false`
  - `custom_fields` `array of object`
    - `id` `string` — Unique identifier for the custom field. — example: `2389328923893298`
    - `name` `string` — Name of the custom field. — example: `employee_level`
    - `ref_name` `string` — Display name of the record a reference-type custom field points at. `value` carries that record's id; this carries its human-readable name, so a consumer does not need a second lookup to render it. — example: `Marketing`
    - `description` `string` — More information about the custom field — example: `Employee Level`
    - `value` `string | number | boolean | object | array of string | number | boolean | object`
      - One of:
        - Option 1: string
        - Option 2: number
        - Option 3: boolean
        - Option 4: object

        - Option 5: array of string | number | boolean | object
  - `tags` `array of string`
  - `updated_by` `string` — The unique identifier of the user who last updated the List. — example: `12345`
  - `created_by` `string` — The unique identifier of the user who created the List. — example: `12345`
  - `updated_at` `string` — The date and time when the List was last updated. — format: `date-time` — example: `2020-09-30T07:43:32.000Z`
  - `created_at` `string` — The date and time when the List was created. — format: `date-time` — example: `2020-09-30T07:43:32.000Z`
- `meta` `object` — Response metadata
  - `items_on_page` `integer` — Number of items returned in the data property of the response — example: `50`
  - `cursors` `object` — Cursors to navigate to previous or next pages through the API
    - `previous` `string` — Cursor to navigate to the previous page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjE=`
    - `current` `string` — Cursor to navigate to the current page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjI=`
    - `next` `string` — Cursor to navigate to the next page of results through the API — example: `em9oby1jcm06OnBhZ2U6OjM=`
  - `total_count` `integer` — Number of records available in total for this resource — example: `1`
  - `warnings` `array of object` — Non-fatal warnings emitted when optional workflow steps failed. Present only when at least one step degraded; the response status remains 200.
    - `type` `string` — Discriminator for the warning kind. — example: `downstream_request_failed`
    - `status_code` `integer` — HTTP status code returned by the failed downstream request, when available. — example: `429`
    - `error` `string` — Short error description from the downstream provider, when available.
    - `operation` `string` — Identifier of the workflow step that failed. — example: `getManager`
    - `message` `string` — Detailed message from the downstream provider, when available.
- `_raw` `object` — Raw response from the integration when raw=true query param is provided

#### 400 — Bad Request

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 401 — Unauthorized

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 402 — Payment Required

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 404 — The specified resource was not found

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### 422 — Unprocessable

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

#### default — Unexpected error

> Standard error response — see [Error Responses](https://developers.apideck.com/errors)

---