Upsert Contact

Create a contact, or update the matching one if it already exists.

The contact is matched inside your organization on email first, then on linkedin_url (both normalized), so re-sending the same person is safe and returns the same id. Fields you send overwrite the stored values; fields you omit are left untouched. 201 is returned for both the create and the update.

company_domain is what links the contact to an account — the account (and its company) is created when it does not exist yet, and company_name is only used for that creation. Sending company_name alone does not link an account.

Requires the contacts:write scope on the API key.

POST

contacts

Upsert Contact

curl --request POST \
  --url https://api.topo.io/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "linkedin_url": "<string>",
  "job_title": "<string>",
  "phone_number": "<string>",
  "company_name": "<string>",
  "company_domain": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: '<string>',
    last_name: '<string>',
    email: '<string>',
    linkedin_url: '<string>',
    job_title: '<string>',
    phone_number: '<string>',
    company_name: '<string>',
    company_domain: '<string>'
  })
};

fetch('https://api.topo.io/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.topo.io/v1/contacts"

payload = {
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "linkedin_url": "<string>",
    "job_title": "<string>",
    "phone_number": "<string>",
    "company_name": "<string>",
    "company_domain": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "first_seen_at": "2023-11-07T05:31:56Z",
  "last_seen_at": "2023-11-07T05:31:56Z",
  "email": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "job_title": "<string>",
  "linkedin_url": "<string>",
  "phone_number": "<string>",
  "city": "<string>",
  "state": "<string>",
  "country": "<string>",
  "profile_picture_url": "<string>",
  "company_name": "<string>",
  "company_domain": "<string>",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "<string>",
    "name": "<string>"
  }
}

Authorizations

Authorization

string

header

required

Bearer API key issued from Settings → Developers.

Body

application/json

Upsert Contact payload

first_name

string | null

First name.

last_name

string | null

Last name.

string | null

Email. At least one of email or linkedin_url is required.

linkedin_url

string | null

LinkedIn profile URL. At least one of email or linkedin_url is required.

job_title

string | null

Job title.

phone_number

string | null

Phone number.

company_name

string | null

Employer name.

company_domain

string | null

Employer's primary domain. Required to link the contact to an account.

Response

201 - application/json

Successful Response

string<uuid>

required

Unique identifier of the contact.

first_seen_at

string<date-time>

required

When this contact was first associated with the organization.

last_seen_at

string<date-time>

required

When this contact was last touched in the organization.

string | null

Email.

first_name

string | null

First name.

last_name

string | null

Last name.

job_title

string | null

Job title.

linkedin_url

string | null

LinkedIn profile URL.

phone_number

string | null

Phone number.

city

string | null

City.

state

string | null

State.

country

string | null

Country.

profile_picture_url

string | null

Profile picture URL.

company_name

string | null

Employer name.

company_domain

string | null

Employer's primary domain.

account_id

string<uuid> | null

Account this contact is linked to. Use it with the Accounts endpoints.

owner_user_id

string<uuid> | null

User who owns this contact, if any.

owner

PublicUserSummary · object | null

Summary of the user who owns this contact.

Hide child attributes

owner.id

string<uuid>

required

Unique identifier of the user.

owner.email

string

required

Email address.

owner.name

string | null

Display name.

Upsert Contact

curl --request POST \
  --url https://api.topo.io/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "first_name": "<string>",
  "last_name": "<string>",
  "email": "<string>",
  "linkedin_url": "<string>",
  "job_title": "<string>",
  "phone_number": "<string>",
  "company_name": "<string>",
  "company_domain": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    first_name: '<string>',
    last_name: '<string>',
    email: '<string>',
    linkedin_url: '<string>',
    job_title: '<string>',
    phone_number: '<string>',
    company_name: '<string>',
    company_domain: '<string>'
  })
};

fetch('https://api.topo.io/v1/contacts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.topo.io/v1/contacts"

payload = {
    "first_name": "<string>",
    "last_name": "<string>",
    "email": "<string>",
    "linkedin_url": "<string>",
    "job_title": "<string>",
    "phone_number": "<string>",
    "company_name": "<string>",
    "company_domain": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "first_seen_at": "2023-11-07T05:31:56Z",
  "last_seen_at": "2023-11-07T05:31:56Z",
  "email": "<string>",
  "first_name": "<string>",
  "last_name": "<string>",
  "job_title": "<string>",
  "linkedin_url": "<string>",
  "phone_number": "<string>",
  "city": "<string>",
  "state": "<string>",
  "country": "<string>",
  "profile_picture_url": "<string>",
  "company_name": "<string>",
  "company_domain": "<string>",
  "account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "<string>",
    "name": "<string>"
  }
}

Overview

Users

Contacts

Accounts

Sequences & Tasks

Events & Webhooks

Upsert Contact

Authorizations

Body

Response