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. A contact can also belong to a company, which groups everyone from the same customer.

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`). Contacts without any activity are always listed last
`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://there-there.app/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,
            "company": {
                "ulid": "01kzx9m6kce637yvd1m95077kr",
                "name": "Acme",
                "domain": "acme.com"
            },
            "ticket_count": 3,
            "last_activity_at": "2025-06-02T14:15:00+00:00"
        }
    ],
    "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
    "meta": { "current_page": 1, "last_page": 2, "per_page": 10, "total": 14 }
}

Get Contact

GET /api/contacts/{contact}

The single contact response wraps the contact under data and includes notes.

company is always present. It is null when the contact belongs to no company.

Create Contact

POST /api/contacts

Request Body

Field	Type	Required	Description
`email`	string	Yes	Unique per workspace
`name`	string	No
`notes`	string	No	Free-text notes

The email is normalized to lowercase on creation.

Update Contact

PUT /api/contacts/{contact}

Request Body

Field	Type	Required	Description
`email`	string	No	Unique per workspace, normalized to lowercase
`name`	string	No
`notes`	string	No	Free-text notes
`company_ulid`	string	No	ULID of the company to attach to

All fields are optional. Omit a field to leave it unchanged. Any member of the workspace can update a contact.

Passing a company_ulid moves the contact to that company. Passing an explicit null detaches it from the company it is in. A ULID that belongs to another workspace returns 404, and nothing on the contact is saved.

Delete Contact

DELETE /api/contacts/{contact}

Admin role required. Returns 204 on success.