Skip to content
CRM Solid Docs
Open app

List contacts

GET
/v1/contacts

Returns a cursor-paginated list of contacts scoped to the authenticated user. Pass after=<id> to fetch the next page. Requires scope contacts:read.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
after
integer

Return contacts with an id strictly less than this value (cursor for next page).

limit
integer
default: 25 >= 1 <= 100

Number of contacts to return. Clamped to 1-100.

platform
string
Allowed values: telegram twitter

Filter by platform.

q
string

Case-insensitive substring search across name, username, and phone.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Paginated contact list.

Cursor-paginated list of contacts.

object
items
Array<object>

A CRM contact record.

object
id
integer
platform

Social platform the contact belongs to.

string
Allowed values: telegram twitter
name
string
nullable
username

Handle without the leading @.

string
nullable
phone
string
nullable
email
string
nullable
company
string
nullable
notes
string
nullable
stage

CRM pipeline stage.

string
leadScore

Lead score 0-100 (higher = hotter). Null when not scored.

integer
nullable
leadScoreIsAi

True when the score was last set by AI, false for a manual override.

boolean
assignedToUserId

Team member the contact is assigned to.

integer
nullable
createdAt
string format: date-time
lastMessageAt
string format: date-time
nullable
hasUnreadMessages
boolean
tags

Attached tags (populated on GET by id, omitted in list responses).

Array<object>
nullable
object
id
integer
name
string
color

Hex color

string
nextCursor

Pass as after on the next request to continue pagination. Null when hasMore is false.

integer
nullable
hasMore

Whether additional pages exist beyond this response.

boolean
Example
{
  "items": [
    {
      "id": 101,
      "platform": "telegram",
      "name": "Acme Inc.",
      "username": "john_doe",
      "phone": null,
      "notes": null,
      "stage": "Lead",
      "createdAt": "2024-03-01T10:00:00Z",
      "lastMessageAt": null,
      "hasUnreadMessages": false
    }
  ],
  "nextCursor": 101,
  "hasMore": false
}

400

Section titled “400 ”

The request body or parameters failed validation.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "bad_request",
  "message": "at least one of name, username, phone is required"
}

401

Section titled “401 ”

Missing or invalid bearer token.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "unauthorized",
  "message": "Invalid bearer principal"
}

403

Section titled “403 ”

The API key does not have the required scope for this operation.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "forbidden",
  "message": "scope contacts:write is required"
}

429

Section titled “429 ”

Per-key rate limit exceeded. Retry after the time indicated by X-RateLimit-Reset.

Standard error envelope for all v1 error responses.

object
error

Machine-readable error code.

string
Allowed values: bad_request not_found conflict unauthorized forbidden rate_limited internal_error
message

Human-readable explanation of the error.

string
details

Optional structured context (field-level validation errors, etc.).

nullable
Example
{
  "error": "rate_limited",
  "message": "rate limit exceeded"
}

Headers

Section titled “Headers ”
X-RateLimit-Limit
integer

Maximum requests allowed per minute for this key.

X-RateLimit-Remaining
integer

Requests remaining in the current window.

X-RateLimit-Reset
integer

Unix timestamp (seconds) when the rate limit window resets.