---
title: "Query contacts"
method: GET
path: "/v1/projects/{project_id}/contacts"
tags: ["Contact"]
---

# Query contacts

`GET /v1/projects/{project_id}/contacts`

## Request

- Base URL: `https://api.telerivet.com`
- URL: `https://api.telerivet.com/v1/projects/{project_id}/contacts`
- Auth: one of:
  - HTTP basic
  - OAuth 2 (authorization code, authorization URL `https://telerivet.com/oauth/authorize`, token URL `https://api.telerivet.com/oauth/token`)

Queries contacts within the given project.

## Path parameters

- `project_id` string, required

## Query parameters

- `group_id` string: ID of Group
- `name` string
- `phone_number` string
- `time_created` integer: Unix timestamp in seconds
- `last_message_time` integer: Unix timestamp in seconds
- `last_incoming_message_time` integer: Unix timestamp in seconds
- `last_outgoing_message_time` integer: Unix timestamp in seconds
- `incoming_message_count` integer
- `outgoing_message_count` integer
- `send_blocked` boolean
- `vars` object
- `sort` 'default' | 'name' | 'phone_number' | 'last_message_time'
- `sort_dir` 'asc' | 'desc'
- `page_size` integer
- `offset` integer
- `marker` string
- `count` boolean

## Response `200`

Successful response. When count=1 parameter is provided, returns {"count": N} instead.

- object
  - `data` Contact[]: Array of results (omitted when count=1)
    - `id` string: ID of the contact
    - `name` string: Name of the contact
    - `phone_number` string: Phone number of the contact
    - `time_created` integer: Time the contact was added in Telerivet
    - `time_updated` integer: Time the contact was last updated in Telerivet
    - `send_blocked` boolean: True if Telerivet is blocked from sending messages to this contact
    - `conversation_status` 'closed' | 'active' | 'handled': Current status of the conversation with this contact
    - `last_message_time` integer, nullable: Last time the contact sent or received a message (null if no messages have been sent or received)
    - `last_incoming_message_time` integer, nullable: Last time a message was received from this contact
    - `last_outgoing_message_time` integer, nullable: Last time a message was sent to this contact
    - `message_count` integer: Total number of non-deleted messages sent to or received from this contact
    - `incoming_message_count` integer: Number of messages received from this contact
    - `outgoing_message_count` integer: Number of messages sent to this contact
    - `last_message_id` string: ID of the last message sent to or received from this contact (null if no messages have been sent or received)
    - `default_route_id` string: ID of the basic route (phone) or custom route that Telerivet will use by default to send messages to this contact (null if using project default route)
    - `group_ids` string[]: List of IDs of groups that this contact belongs to
    - `vars` object: Custom variables stored for this contact. Variable names may be up to 32 characters in length and can contain the characters a-z, A-Z, 0-9, and _. Values may be strings, numbers, or boolean (true/false). String values may be up to 4096 bytes in length when encoded as UTF-8. Up to 100 variables are supported per object. Setting a variable to null will delete the variable.
    - `project_id` string: ID of the project this contact belongs to
    - `url` string: URL to this contact in the Telerivet web app
  - `truncated` boolean: True if there are more results
  - `next_marker` string: Marker for pagination
  - `page_size` integer: Number of results per page
  - `sort_dir` 'asc' | 'desc': Sort direction
  - `count` integer: Total count of matching items (only when count=1 parameter is provided)

## Other responses

- `400`: Invalid request parameters
- `401`: Invalid or missing API key or Bearer token
- `404`: Resource not found

---

[API](https://skmtc.dev/telerivet/apis/telerivet-api.md) · [All operations](https://skmtc.dev/telerivet/apis/telerivet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/telerivet/apis/telerivet-api/revisions/4e14b1c8d917?raw)