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

# List Contacts — Shilo API Reference

> Retrieve a paginated list of contacts in your Shilo organization. Filter by external ID, phone, email, or name. Supports cursor-based pagination.

Use this endpoint to retrieve all contacts in your Shilo organization. Results are paginated and can be filtered by external contact ID, phone number, email address, or name. Use the `cursor` returned in the pagination object to walk through large result sets page by page.

## Endpoint

```
GET https://api.shilo.ai/api/v1/contacts
```

## Authentication

Include your API key in the request header:

```
x-api-key: YOUR_API_KEY
```

## Query Parameters

<ParamField query="limit" type="number" default="50">
  Maximum number of contacts to return per page. Accepted range is 1–100.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor returned by a previous response. Pass this value to retrieve the next page of results.
</ParamField>

<ParamField query="sort" type="string">
  Sort order by created date. Accepted values: `asc`, `desc`.
</ParamField>

<ParamField query="external_contact_id" type="string">
  Filter by your CRM or external system's contact ID. Exact match only.
</ParamField>

<ParamField query="phone" type="string">
  Filter by phone number. Matched after digit-normalizing both the query and stored values, so formatting differences are ignored.
</ParamField>

<ParamField query="email" type="string">
  Filter by email address. Case-insensitive exact match.
</ParamField>

<ParamField query="name" type="string">
  Filter by contact name. Case-insensitive partial match — useful for search-as-you-type UIs.
</ParamField>

## Response

A successful request returns HTTP `200` with a `ContactsResponseDto` object.

### Response Fields

<ResponseField name="data" type="array">
  An array of Contact objects matching your query filters.

  <Expandable title="Contact object">
    <ResponseField name="id" type="string">
      The Shilo-assigned UUID for this contact.
    </ResponseField>

    <ResponseField name="external_contact_id" type="string">
      The contact ID from your external CRM or system of record.
    </ResponseField>

    <ResponseField name="name" type="string">
      Full display name of the contact.
    </ResponseField>

    <ResponseField name="first_name" type="string">
      Contact's first name.
    </ResponseField>

    <ResponseField name="last_name" type="string">
      Contact's last name.
    </ResponseField>

    <ResponseField name="phone" type="string">
      Primary phone number for the contact.
    </ResponseField>

    <ResponseField name="emails" type="array of strings">
      List of email addresses associated with the contact.
    </ResponseField>

    <ResponseField name="stage" type="string">
      Human-readable label for the contact's current pipeline stage.
    </ResponseField>

    <ResponseField name="stage_id" type="string">
      Your system's ID for the pipeline stage.
    </ResponseField>

    <ResponseField name="source" type="string">
      Human-readable label for the contact's lead source.
    </ResponseField>

    <ResponseField name="source_id" type="string">
      Your system's ID for the lead source.
    </ResponseField>

    <ResponseField name="tags" type="array of strings">
      Tags applied to the contact.
    </ResponseField>

    <ResponseField name="created_date" type="string">
      ISO-8601 timestamp indicating when this contact was created in Shilo.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="pagination" type="object">
  Pagination metadata for the current response.

  <Expandable title="Pagination object">
    <ResponseField name="has_more" type="boolean">
      `true` if additional pages of results exist beyond the current page.
    </ResponseField>

    <ResponseField name="next_cursor" type="string | null">
      Cursor value to pass in your next request to retrieve the following page. `null` when no further pages are available.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "data": [
    {
      "id": "ee6f2136-b94a-4438-9335-3acf5b2a0d31",
      "external_contact_id": "4534",
      "name": "Jamie Customer",
      "first_name": "Jamie",
      "last_name": "Customer",
      "phone": "(555) 555-9999",
      "emails": ["jamie@example.com"],
      "stage": "Negotiation",
      "stage_id": "stage-99",
      "source": "Zillow",
      "source_id": "src-7",
      "tags": ["hot-lead"],
      "created_date": "2024-09-01T10:00:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}
```

## Error Codes

| Status | Meaning                     |
| ------ | --------------------------- |
| `401`  | Missing or invalid API key. |

## Example Request

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/contacts?limit=50&sort=asc" \
  -H "x-api-key: YOUR_API_KEY"
```

### Filter by name

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/contacts?name=jamie" \
  -H "x-api-key: YOUR_API_KEY"
```

### Paginate with a cursor

```bash theme={null}
curl -X GET "https://api.shilo.ai/api/v1/contacts?limit=50&cursor=NEXT_CURSOR_VALUE" \
  -H "x-api-key: YOUR_API_KEY"
```