Skip to main content
GET
Retrieve a contact

Authorizations

Authorization
string
header
required

A workspace API token (sk_live_...) or an OAuth access token (oat_live_...). Create workspace tokens in Settings > API. Send either as Authorization: Bearer <token>.

Path Parameters

contact_id
string
required

Unique identifier for a contact.

Pattern: ^con_[0-9a-f]{32}$
Example:

"con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

Query Parameters

expand
string | null

Comma-separated relationships to inline in the response, e.g. organization. Unexpanded relations are still identified by their *_id field.

Example:

"organization"

fields
string | null

Comma-separated fields to return. object and id are always included. Reduces payload size, not query cost.

Example:

"name,email,organization_id"

Response

Successful Response

A person in your CRM.

created_at
string<date-time>
required
id
string
required

Unique identifier for a contact.

Pattern: ^con_[0-9a-f]{32}$
Example:

"con_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

status
enum<string>
required

Where the contact stands.

Available options:
open,
on_hold,
won,
lost
updated_at
string<date-time>
required
visibility
enum<string>
required

Who in the workspace can see this record. A workspace token sees every record regardless; an OAuth token sees what the person who authorized it can see.

Available options:
private,
team,
team_and_subteams,
company
address
string | null
avatar_url
string | null

Short-lived signed URL; do not store it.

channels
ContactChannel · object[]
city
string | null
company_name
string | null

Legacy alias for organization. The text is kept on the contact, and a contact that has no organization yet is also linked to the organization this name matches, or to a new one when none does. To say which organization a contact belongs to, send organization, which also tells you how the name was resolved.

custom_fields
Custom Fields · object

Every custom field defined on contacts in this workspace, keyed by field key and typed from its definition. Unset fields are null, so reading any contact shows the full set of keys in use.

email
string | null
external_id
string | null

Your own id for this record, when you set one.

first_name
string | null
job_title
string | null
last_name
string | null
lost_reason
string | null

Name of the reason, when status is lost.

name
string | null

Display name. Derived from first_name and last_name.

object
string
default:contact
Allowed value: "contact"
organization
Organization · object | null

Populated only when organization is in expand.

organization_id
string | null

Unique identifier for an organization.

Pattern: ^org_[0-9a-f]{32}$
Example:

"org_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

owner
Owner · object | null

Whoever is responsible for this record. Always populated when the record has an owner — this is not an expand target.

owner_id
string | null
deprecated

Unique identifier for an user.

Pattern: ^usr_[0-9a-f]{32}$
Example:

"usr_9f2ac41d8b7e4a51b0d3e6f7a1c2d3e4"

phone
string | null

E.164. Normalized on write.

score
enum<string> | null

How warm a contact is.

Available options:
cold,
warm,
hot
state
string | null
tags
Tag · object[]