Upsert Account

Create an account, or return the matching one if it already exists.

The account is matched inside your organization on domain (normalized), so re-sending the same company is safe and returns the same id. name is only used when the account (and its company) does not exist yet. 201 is returned for both the create and the match.

Upserting a contact with company_domain (POST /v1/contacts) creates the account implicitly — use this endpoint when you want to push companies before knowing which people to pursue.

Requires the accounts:write scope on the API key.

POST

/

v1

/

accounts

Upsert Account

curl --request POST \
  --url https://api.topo.io/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "<string>",
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({domain: '<string>', name: '<string>'})
};

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

import requests

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

payload = {
    "domain": "<string>",
    "name": "<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",
  "name": "<string>",
  "domain": "<string>",
  "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 Account payload

domain

string

required

Primary company domain. The account is matched inside your organization on this domain.

Minimum string length: 1

name

string | null

Company name. Only used when the account is created.

Response

201 - application/json

Successful Response

id

string<uuid>

required

Unique identifier of the account.

first_seen_at

string<date-time>

required

When this account was first associated with the organization.

last_seen_at

string<date-time>

required

When this account was last touched in the organization.

name

string | null

Company name.

domain

string | null

Primary company domain.

owner_user_id

string<uuid> | null

User who owns this account, if any.

owner

PublicUserSummary · object | null

Summary of the user who owns this account.

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 Account

curl --request POST \
  --url https://api.topo.io/v1/accounts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "domain": "<string>",
  "name": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({domain: '<string>', name: '<string>'})
};

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

import requests

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

payload = {
    "domain": "<string>",
    "name": "<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",
  "name": "<string>",
  "domain": "<string>",
  "owner_user_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "owner": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "email": "<string>",
    "name": "<string>"
  }
}