Clients

List client contacts

List the contacts saved for a client.

GET /teams/{teamId}/clients/{clientId}/contacts

Returns the contacts saved for the client, ordered by first name and then by last name. Each entry is a full contact object. A contact is a person at the client, saved on the client's Contacts tab in the Hub.

Authentication: Bearer token · Permission:clients:read · Team permission:client_contacts.read · Rate limit: default (120 / 60s)

The key holder's role must include View client contacts. Every standard role includes it. See the permissions matrix.

Path parameters

teamId

string · uuid v7 required

The team the client belongs to.

clientId

string · uuid v7 required

The ID of the client whose contacts to list, from list clients.

Query parameters

All query parameters are optional. The API applies them in this order: filter, then sortBy, then limit, then outputFields.

filter

string

Keep only the contacts that match, in the form field:operator:value. The operators are equals, notEquals, contains, notContains, greaterThan and lesserThan. Text comparisons ignore case. Repeat the parameter to apply more than one filter; a contact must match all of them. The field must be a top-level field of the contact object, for example jobTitle:contains:director.

sortBy

string

Sort the contacts, in the form field or field:asc or field:desc, for example lastName:asc. Repeat the parameter to sort by more than one field; the first one is the primary sort. Without sortBy, contacts are ordered by first name and then by last name.

limit

integer

The maximum number of contacts to return. Must be a positive whole number.

outputFields

string

The fields to keep on each contact, comma-separated, for example firstName,email. id is always kept. Use a dot to keep one key of a nested object, for example client.name. Without outputFields, every field is returned.

An unknown field in filter or sortBy returns 400, and the message lists the fields you can use. When the client has no contacts, the API returns an empty array and does not check the field names.

Request

curl "https://api.twominutereports.com/v1/teams/0190f8b0-1a2b-7c3d-8e4f-5a6b7c8d9e0f/clients/0190f8c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f/contacts?sortBy=lastName:asc" \
  -H "Authorization: Bearer tmrc_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Response

Returns an array of contact objects. The array is empty if the client has no contacts.

{
  "success": true,
  "data": [
    {
      "id": "0190f8d2-6b7c-7d8e-9f0a-1b2c3d4e5f6a",
      "clientId": "0190f8c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "client": {
        "id": "0190f8c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "name": "Acme Corp",
        "logoUrl": "https://assets.gox.ai/tmr/logos/acme.png"
      },
      "firstName": "Sarah",
      "lastName": "Chen",
      "email": "[email protected]",
      "jobTitle": "Marketing Director",
      "note": "Wants the monthly report before the board meeting.",
      "briefingCount": 2,
      "createdAt": "2026-10-02T09:30:00.000Z",
      "updatedAt": "2026-10-08T14:05:00.000Z",
      "createdBy": {
        "id": "0190f8b7-3c4d-7e5f-9a0b-1c2d3e4f5a6b",
        "name": "Priya Raman",
        "firstName": "Priya",
        "lastName": "Raman",
        "avatarUrl": null,
        "email": "[email protected]"
      },
      "updatedBy": {
        "id": "0190f8b8-4d5e-7f6a-8b1c-2d3e4f5a6b7c",
        "name": "Arun Menon",
        "firstName": "Arun",
        "lastName": "Menon",
        "avatarUrl": null,
        "email": "[email protected]"
      }
    },
    {
      "id": "0190f8d3-7c8d-7e9f-8a1b-2c3d4e5f6a7b",
      "clientId": "0190f8c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
      "client": {
        "id": "0190f8c0-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
        "name": "Acme Corp",
        "logoUrl": "https://assets.gox.ai/tmr/logos/acme.png"
      },
      "firstName": "Daniel",
      "lastName": "Park",
      "email": "[email protected]",
      "jobTitle": "Head of Growth",
      "note": null,
      "briefingCount": 0,
      "createdAt": "2026-10-03T11:12:00.000Z",
      "updatedAt": null,
      "createdBy": {
        "id": "0190f8b7-3c4d-7e5f-9a0b-1c2d3e4f5a6b",
        "name": "Priya Raman",
        "firstName": "Priya",
        "lastName": "Raman",
        "avatarUrl": null,
        "email": "[email protected]"
      },
      "updatedBy": null
    }
  ]
}

Returned when a query parameter is not in the expected form, or when filter or sortBy names a field that the contact object does not have.

{
  "success": false,
  "error": { "code": "BAD_REQUEST", "message": "Validation error: Invalid sortBy 'lastName:up'. Expected 'field' or 'field:asc|desc', e.g. 'name:desc'. at \"sortBy\"" }
}

The API key does not have the clients:read scope.

{
  "success": false,
  "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "This API key is missing the `clients:read` permission required for this endpoint. Grant it to the key under Settings → API Keys (https://hub.twominutereports.com/settings?tab=user-api-keys), or use a key that has it." }
}

Returned when you are not a member of the team.

{
  "success": false,
  "error": { "code": "FORBIDDEN", "message": "Access denied" }
}

Returned when the client does not exist or does not belong to this team.

{
  "success": false,
  "error": { "code": "NOT_FOUND", "message": "Client not found" }
}

Delete client account

Unlink a connector account from a client.

Get client contact

Retrieve a single client contact by its ID.