Skip to main content
GET
List conversations

Authorizations

Authorization
string
header
required

Pass Authorization: Bearer <credential>, where the credential is either:

  • an API key (sk_…), generated by an organization admin in Settings, for scripts and automation;
  • an access token from tth auth login (the TalkToHumans CLI), which any member of the workspace can use.

Both resolve to the same organization and user. A login token acts in the user's workspace: one with no workspace yet returns 403 workspace_setup_required, and one in several workspaces returns 403 forbidden (use an API key instead).

Query Parameters

account_id
string[]

LinkedIn account IDs returned by GET /v1/accounts.

Repeat the query parameter for multiple accounts. The backend also accepts comma-separated values. If an explicit account target is not accessible to this credential, the API returns 403 account_shared_access_required.

Pattern: ^[1-9][0-9]*$
view_id
string

Filter by a saved inbox. Accepts the view id or an unambiguous public_id from GET /v1/views. Uses the view's account and filters. An explicit account_id scope must include that account. Results keep the endpoint's normal ordering.

contact_id
string

Filter by TalkToHumans contact ID. Use a positive integer encoded as a string.

Pattern: ^[1-9][0-9]*$
filters
string

JSON array of filters conversations must all match, in the same shape as an inbox's filters. Field keys name their record, such as member.full_name or conversation.reply_state. Use conversation.messages to match the text of synced messages. Requires exactly one account: pass one account_id when several are accessible.

sorts
string

JSON array of sorts, first entry first, in the same shape as an inbox's sorts. Requires exactly one account. Pages still follow cursor.

limit
integer
default:10

Page size. Defaults to 10. Values above 25 are clamped to 25.

Required range: 1 <= x <= 25
cursor
string

Opaque cursor from the previous response's pagination.next_cursor.

Response

Conversations matching the filters.

data
object
required