Skip to main content
The Contacts API gives you read access to every person Topo has associated with your workspace, along with the ability to attach arbitrary key-value variables to a contact or its employer. Variables are the primary way to pass CRM data, lead scores, or personalization tokens into Topo’s AI sequences.
All read endpoints require the contacts:read scope. Variable write and delete endpoints require contacts:write.

​
The Contact object

​
id
string (UUID)
required
Unique identifier for the contact within your workspace.
​
email
string | null
Primary email address.
​
first_name
string | null
First name.
​
last_name
string | null
Last name.
​
job_title
string | null
Current job title.
​
linkedin_url
string | null
Canonical LinkedIn profile URL.
​
phone_number
string | null
Phone number. Returned unmasked to callers holding the contacts:read scope — access is governed by API key scope, not masking.
​
city
string | null
City of residence or work.
​
state
string | null
State or region.
​
country
string | null
Country.
​
profile_picture_url
string | null
URL to the contact’s profile photo.
​
company_name
string | null
Name of the contact’s current employer.
​
company_domain
string | null
Primary domain of the contact’s current employer (e.g. acme.com).
​
first_seen_at
string (ISO 8601)
Timestamp when this person was first associated with your workspace.
​
last_seen_at
string (ISO 8601)
Timestamp when this person was last touched (e.g. added to a list or sequence) in your workspace.

​
List contacts

GET /v1/contacts Returns a paginated list of contacts belonging to your workspace. Use the query parameters below to filter and sort results.

​
Query parameters

​
email
string
Case-insensitive exact match on the contact’s email address.
​
linkedin_url
string
Filters by LinkedIn profile URL. Topo normalizes the provided value and matches it against all known canonical variants (with or without trailing slash, www. prefix, etc.).
​
contact_id
string (UUID)
Fetch a specific contact by its ID. Useful when you already know the ID but want to reuse the list endpoint’s filtering envelope.
​
first_seen_after
string (ISO 8601)
Returns contacts first associated with your workspace strictly after this timestamp.
​
last_seen_after
string (ISO 8601)
Returns contacts last touched strictly after this timestamp.
​
sort_by
string
Field to sort results by. One of first_seen_at, last_seen_at, or email.
​
page
integer
default:"1"
Page number (1-indexed).
​
size
integer
default:"10"
Number of results per page. Maximum 100.

​
Response

Returns a paginated envelope.
​
items
array
Array of Contact objects on the current page.
​
total_count
integer
Total number of contacts matching the query.
​
total_pages
integer
Total number of pages at the current page size.
​
has_more
boolean
true if there are additional pages after the current one.
curl -G https://api.topo.io/v1/contacts \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  --data-urlencode "sort_by=last_seen_at" \
  --data-urlencode "size=25"

​
Get a contact

GET /v1/contacts/{contact_id} Fetches a single contact by its UUID.

​
Path parameters

​
contact_id
string (UUID)
required
The unique identifier of the contact.
curl https://api.topo.io/v1/contacts/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer topo_sk_live_abc123"

​
Get contact variables

GET /v1/contacts/{contact_id}/variables Returns the custom variables stored on a contact and on its associated company. Variables are plain string key-value pairs you can write via the PATCH endpoint and reference inside Topo sequence templates.

​
Path parameters

​
contact_id
string (UUID)
required
The unique identifier of the contact.

​
Response

​
contact_variables
object
Key-value map of custom variables scoped to the individual contact. Values are strings or null.
​
company_variables
object
Key-value map of custom variables scoped to the contact’s employer. Values are strings or null.
curl https://api.topo.io/v1/contacts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/variables \
  -H "Authorization: Bearer topo_sk_live_abc123"
Example response: 
{
  "contact_variables": {
    "crm_lead_score": "82",
    "persona": "champion"
  },
  "company_variables": {
    "arr_band": "1M-5M",
    "industry": "FinTech"
  }
}

​
Update contact variables

PATCH /v1/contacts/{contact_id}/variables Merges key-value pairs into the contact’s or company’s variable maps. This is an upsert operation — provided keys are written or overwritten, and all other existing keys are left untouched.
Each scope (contact or company) holds a maximum of 200 variables. Setting a key’s value to null clears the value but does not free its slot toward the limit. Use the Delete variable endpoint to fully remove a key.
If the contact is not yet linked to your workspace, Topo creates the link automatically so the variables can be stored. Writing only company_variables still links the contact.

​
Path parameters

​
contact_id
string (UUID)
required
The unique identifier of the contact.

​
Request body

​
contact_variables
object
Key-value pairs to merge into the contact’s variables. Existing keys not present here are preserved.
​
company_variables
object
Key-value pairs to merge into the company’s variables. Existing keys not present here are preserved.

​
Response

Returns the full updated variables object with both contact_variables and company_variables. 
curl -X PATCH https://api.topo.io/v1/contacts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/variables \
  -H "Authorization: Bearer topo_sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_variables": {
      "crm_lead_score": "91",
      "persona": "economic_buyer"
    },
    "company_variables": {
      "arr_band": "5M-20M"
    }
  }'

​
Delete a contact variable

DELETE /v1/contacts/{contact_id}/variables/{key} Permanently removes a single variable key from the contact or company scope. Unlike setting a value to null, this also frees the key’s slot toward the 200-variable limit.

​
Path parameters

​
contact_id
string (UUID)
required
The unique identifier of the contact.
​
key
string
required
The variable key to delete.

​
Query parameters

​
scope
string
required
Which variable map to delete from. Must be either contact or company.

​
Response

Returns the updated contact_variables and company_variables maps after the deletion. 
curl -X DELETE \
  "https://api.topo.io/v1/contacts/a1b2c3d4-e5f6-7890-abcd-ef1234567890/variables/crm_lead_score?scope=contact" \
  -H "Authorization: Bearer topo_sk_live_abc123"