Skip to main content
POST
Create or upsert a contact

Authorizations

Authorization
string
header
required

Bearer API key. Secret server keys start with gt_live_; client-safe browser keys start with gt_pub_ (write-only, origin-pinned). Create and scope keys in Settings → API Keys.

Body

application/json

Create a Person at a Company, or with upsert: true create or update. Name the Company with accountId or accountExternalId. name is required unless upsert is true and an email is supplied, or the Person already exists at another Company.

accountId
string<uuid>
required

The Company id. It must belong to your workspace.

accountExternalId
string

The Company externalId, used when you do not hold the Company id. If no Company has this externalId, GainTrace creates one, and that counts against your Company limit. The new Company fires the company.created webhook but does not start Company-created Flows. Ignored when accountId is a string.

Maximum string length: 100
accountName
string

The name for a Company created through accountExternalId. Defaults to the externalId.

upsert
boolean
default:false

When true, a Person who already exists at this Company is updated and returned with 200, instead of failing with 409. traits are merged into the stored traits, not replaced.

name
string
Required string length: 1 - 255
email
string<email> | null
Maximum string length: 255
externalId
string | null
Maximum string length: 255
phone
string | null
Maximum string length: 50
role
string | null
Maximum string length: 100
contactRole
enum<string>
Available options:
decision_maker,
champion,
end_user,
billing,
influencer,
executive_sponsor,
technical,
other
isChampion
boolean
traits
object | null
linkedinUrl
string | null
Maximum string length: 2000
avatarUrl
string | null
Maximum string length: 2000

Response

Updated through upsert.

data
object

One Person at one Company. A Person who belongs to several Companies is returned as one record per Company, each with its own id and accountId.