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

# Get a List by ID

> Returns a single CSV contact list with all its contacts. Supports searching, sorting, and paginating contacts.

Returns a single CSV contact list with all its contacts. Supports searching, sorting, and paginating the contacts within the list.

### Path Parameters

* **id** (*required*, string): CSV contact list ID

### Query Parameters

| Parameter | Type   | Description                                                                                            |
| --------- | ------ | ------------------------------------------------------------------------------------------------------ |
| `search`  | string | Search contacts by first name, last name, email, or company (case-insensitive)                         |
| `sort`    | string | Sort contacts by field. Prefix with `-` for descending. Examples: `first_name`, `-company`, `priority` |
| `page`    | number | Page number for contacts. Default: 1                                                                   |
| `limit`   | number | Contacts per page. Default: 50                                                                         |

### Response

Returns the list metadata and a paginated array of contacts:

| Field      | Type   | Description                           |
| ---------- | ------ | ------------------------------------- |
| `_id`      | string | Unique identifier of the contact list |
| `name`     | string | Name of the list                      |
| `user`     | string | ID of the user who owns the list      |
| `contacts` | array  | Array of contact objects              |

Each contact object includes:

| Field           | Type   | Description          |
| --------------- | ------ | -------------------- |
| `_id`           | string | Contact ID           |
| `first_name`    | string | First name           |
| `last_name`     | string | Last name            |
| `email`         | string | Email address        |
| `company`       | string | Company name         |
| `title`         | string | Job title            |
| `phone_numbers` | array  | Phone numbers        |
| `linkedin`      | string | LinkedIn profile URL |
| `website`       | string | Website URL          |
| `notes`         | string | Notes                |
| `priority`      | number | Priority             |
| `timezone`      | string | Timezone             |
| `custom_fields` | array  | Custom fields        |

### Example Requests

```bash theme={null}
# Get a list with all contacts
GET /v1/contact-lists/csv/507f1f77bcf86cd799439011

# Search contacts by name
GET /v1/contact-lists/csv/507f1f77bcf86cd799439011?search=john

# Sort contacts by company, page 2
GET /v1/contact-lists/csv/507f1f77bcf86cd799439011?sort=company&page=2&limit=20
```

### Errors

| Status | Description                |
| ------ | -------------------------- |
| 404    | CSV contact list not found |


## OpenAPI

````yaml GET /v1/contact-lists/csv/{id}
openapi: 3.0.1
info:
  title: Salesfinity API
  description: API documentation for Salesfinity platform
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://client-api.salesfinity.co
security:
  - ApiKeyAuth: []
paths:
  /v1/contact-lists/csv/{id}:
    get:
      tags:
        - Contact Lists
      summary: Get a CSV contact list by ID
      description: >-
        Returns a single CSV contact list with all its contacts. Supports
        searching, sorting, and paginating contacts.
      operationId: get-contact-list-by-id
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: CSV contact list ID
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: Search contacts by first name, last name, email, or company
        - name: sort
          in: query
          required: false
          schema:
            type: string
          description: Sort contacts by field. Prefix with - for descending
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number for contacts
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 50
          description: Contacts per page
      responses:
        '200':
          description: CSV contact list retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CSVListDetailResponse'
        '404':
          description: CSV contact list not found
components:
  schemas:
    CSVListDetailResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            _id:
              type: string
            name:
              type: string
            user:
              type: string
            contacts:
              type: array
              items:
                $ref: '#/components/schemas/CSVContactObject'
        pagination:
          type: object
          properties:
            total:
              type: integer
            page:
              type: integer
            next:
              type: integer
              nullable: true
    CSVContactObject:
      type: object
      properties:
        _id:
          type: string
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
        company:
          type: string
        title:
          type: string
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/NumbersDTO'
        linkedin:
          type: string
        website:
          type: string
        notes:
          type: string
        account:
          type: string
        priority:
          type: number
        timezone:
          type: string
        custom_fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomFieldInputDTO'
    NumbersDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - mobile
            - direct
            - office
        number:
          type: string
        country_code:
          type: string
        extension:
          type: string
      required:
        - type
        - number
    CustomFieldInputDTO:
      type: object
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - boolean
          description: Field data type
        label:
          type: string
          maxLength: 100
          description: Display label for the field
        value:
          description: Field value (string, number, boolean, or string array)
      required:
        - type
        - label
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````