Get a contact by id

GET

/v1/contacts/{id}

• Production

Returns a single contact from the active workspace, with its tags and custom field values. Returns 404 if the contact does not exist or belongs to a workspace the key cannot address. Requires scope contacts:read.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

integer

Header Parameters

X-Workspace-Id

integer

Act on this workspace’s shared CRM pool. Membership is verified on every request, so an id you do not belong to falls back to personal scope rather than widening access. Omit it to use your default workspace. Applies to every CRM endpoint, not only the ones that list it here.

Responses

200

Contact found.

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

externalId

The contact’s id in your own system. The stable key the batch endpoint upserts on.

string

nullable <= 100 characters

country

string

nullable

city

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

ownerUserId

Workspace member the row is filed under. Differs from the caller in a shared pool.

integer

nullable

pipelineId

Custom pipeline board the contact sits on.

integer

nullable

pipelineStageId

Column within pipelineId.

integer

nullable

source

How the contact entered the CRM (OutboundMessage, InboundMessage, Manual, CsvImport, Extension, …).

string

isArchived

True once the contact has been soft-deleted or archived.

boolean

createdAt

string format: date-time

updatedAt

string format: date-time

nullable

lastMessageAt

string format: date-time

nullable

hasUnreadMessages

boolean

customFields

Custom field values keyed by field key. Null when the contact has none.

object

tags

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

Array<object>

nullable

object

id

integer

name

string

color

Hex color

string

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 payment_required provider_rejected 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

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 payment_required provider_rejected 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"
}

404

The requested resource does not exist or is not owned by the caller.

Standard error envelope for all v1 error responses.

object

error

Machine-readable error code.

string

Allowed values: bad_request not_found conflict unauthorized forbidden payment_required provider_rejected rate_limited internal_error

message

Human-readable explanation of the error.

string

details

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

nullable

Example

{
  "error": "not_found",
  "message": "contact not found"
}

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 payment_required provider_rejected 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

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.