Contacts

Overview

Contacts represent the people who submit tickets to your helpdesk. Each contact belongs to a workspace and is associated with one or more tickets. The API provides read access to contacts with filtering and sorting capabilities.

List Contacts

Retrieve a paginated list of contacts in the current workspace.

GET /api/contacts

Query Parameters

Parameter	Type	Description
per_page	integer	Results per page (default: 25, max: 100)
sort	string	Sort field: name, created_at, last_activity. Prefix with - for descending (default: name)
filter[name]	string	Partial match on contact name
filter[email]	string	Partial match on contact email
filter[search]	string	Search across both name and email

Example Request

curl "https://app.therethere.com/api/contacts?filter[search]=john&sort=-last_activity&per_page=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Example Response

{
    "data": [
        {
            "id": 12,
            "ulid": "01HX9F3K2N...",
            "name": "John Doe",
            "email": "john@customer.com",
            "avatar_url": null,
            "ticket_count": 3,
            "last_activity_at": "2025-06-02T14:15:00+00:00"
        },
        {
            "id": 15,
            "ulid": "01HX9G7P4Q...",
            "name": "Johnny Appleseed",
            "email": "johnny@example.com",
            "avatar_url": "https://app.therethere.com/avatars/johnny.jpg",
            "ticket_count": 1,
            "last_activity_at": "2025-05-28T09:00:00+00:00"
        }
    ],
    "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
    "meta": { "current_page": 1, "last_page": 2, "per_page": 10, "total": 14 }
}

Get Contact

Retrieve a single contact with additional details including notes and ticket count.

GET /api/contacts/{id}

Example Request

curl https://app.therethere.com/api/contacts/12 \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Example Response

{
    "contact": {
        "id": 12,
        "ulid": "01HX9F3K2N...",
        "name": "John Doe",
        "email": "john@customer.com",
        "avatar_url": null,
        "ticket_count": 3,
        "last_activity_at": "2025-06-02T14:15:00+00:00",
        "notes": "VIP customer, prefers email communication."
    }
}

The single contact response includes the notes field, which contains free text notes that workspace members have added about this contact. The ticket_count reflects the total number of tickets associated with this contact across all statuses.

Filtering Tips

The search filter performs a case insensitive partial match on both the name and email fields simultaneously, making it useful for building autocomplete or search interfaces. For more targeted lookups, use the name or email filters individually.

Sorting by last_activity orders contacts by the creation date of their most recent ticket, which is helpful for identifying recently active customers.