contacts

Upsert Contact

Changed on

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/v1/contacts

Request

  • Base URL: https://api.topo.io
  • URL: https://api.topo.io/v1/contacts
  • Auth: HTTP bearer

Request body

first_namestring nullable

First name.

last_namestring nullable

Last name.

emailstring nullable

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

linkedin_urlstring nullable

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

job_titlestring nullable

Job title.

phone_numberstring nullable

Phone number.

company_namestring nullable

Employer name.

company_domainstring nullable

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

Response

Successful Response

idstring uuid required

Unique identifier of the contact.

emailstring nullable

Email.

first_namestring nullable

First name.

last_namestring nullable

Last name.

job_titlestring nullable

Job title.

linkedin_urlstring nullable

LinkedIn profile URL.

phone_numberstring nullable

Phone number.

citystring nullable

City.

statestring nullable

State.

countrystring nullable

Country.

profile_picture_urlstring nullable

Profile picture URL.

company_namestring nullable

Employer name.

company_domainstring nullable

Employer's primary domain.

account_idstring uuid nullable

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

owner_user_idstring uuid nullable

User who owns this contact, if any.

first_seen_atstring date-time required

When this contact was first associated with the organization.

last_seen_atstring date-time required

When this contact was last touched in the organization.

Changes