List Contacts — Shilo API Reference

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

number

default:"50"

Maximum number of contacts to return per page. Accepted range is 1–100.

string

Pagination cursor returned by a previous response. Pass this value to retrieve the next page of results.

string

Sort order by created date. Accepted values: asc, desc.

string

Filter by your CRM or external system’s contact ID. Exact match only.

string

Filter by phone number. Matched after digit-normalizing both the query and stored values, so formatting differences are ignored.

string

Filter by email address. Case-insensitive exact match.

string

Filter by contact name. Case-insensitive partial match — useful for search-as-you-type UIs.

Response

A successful request returns HTTP 200 with a ContactsResponseDto object.

Response Fields

array

An array of Contact objects matching your query filters.

Show Contact object

string

The Shilo-assigned UUID for this contact.

string

The contact ID from your external CRM or system of record.

string

Full display name of the contact.

string

Contact’s first name.

string

Contact’s last name.

string

Primary phone number for the contact.

array of strings

List of email addresses associated with the contact.

string

Human-readable label for the contact’s current pipeline stage.

string

Your system’s ID for the pipeline stage.

string

Human-readable label for the contact’s lead source.

string

Your system’s ID for the lead source.

array of strings

Tags applied to the contact.

string

ISO-8601 timestamp indicating when this contact was created in Shilo.

object

Pagination metadata for the current response.

Show Pagination object

boolean

true if additional pages of results exist beyond the current page.

string | null

Cursor value to pass in your next request to retrieve the following page. null when no further pages are available.

Example Response

{
  "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

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

Filter by name

curl -X GET "https://api.shilo.ai/api/v1/contacts?name=jamie" \
  -H "x-api-key: YOUR_API_KEY"

Paginate with a cursor

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

Overview

Calls

Appointments

Roleplays

Contacts

Users

Invitations

Metrics

Coaching

List Contacts — Shilo API Reference

Endpoint

Authentication

Query Parameters

Response

Response Fields

Example Response

Error Codes

Example Request

Filter by name

Paginate with a cursor

​Endpoint

​Authentication

​Query Parameters

​Response

​Response Fields

​Example Response

​Error Codes

​Example Request

​Filter by name

​Paginate with a cursor

Endpoint

Authentication

Query Parameters

Response

Response Fields

Example Response

Error Codes

Example Request

Filter by name

Paginate with a cursor