Create or upsert a person

curl --request POST \
  --url https://app.gaintrace.com/api/v1/people \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountExternalId": "acme",
  "accountName": "Acme Inc",
  "name": "Ana Ruiz",
  "email": "[email protected]",
  "externalId": "user_8812",
  "contactRole": "decision_maker",
  "upsert": true,
  "traits": {
    "plan_tier": "growth"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountExternalId: 'acme',
    accountName: 'Acme Inc',
    name: 'Ana Ruiz',
    email: '[email protected]',
    externalId: 'user_8812',
    contactRole: 'decision_maker',
    upsert: true,
    traits: {plan_tier: 'growth'}
  })
};

fetch('https://app.gaintrace.com/api/v1/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.gaintrace.com/api/v1/people"

payload = {
    "accountExternalId": "acme",
    "accountName": "Acme Inc",
    "name": "Ana Ruiz",
    "email": "[email protected]",
    "externalId": "user_8812",
    "contactRole": "decision_maker",
    "upsert": True,
    "traits": { "plan_tier": "growth" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "[email protected]",
    "externalId": "<string>",
    "phone": "<string>",
    "role": "<string>",
    "contactRole": "decision_maker",
    "isChampion": true,
    "traits": {},
    "linkedinUrl": "<string>",
    "avatarUrl": "<string>",
    "lastSeenAt": "2023-11-07T05:31:56Z",
    "engagementScore": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "archivedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "[email protected]",
    "externalId": "<string>",
    "phone": "<string>",
    "role": "<string>",
    "contactRole": "decision_maker",
    "isChampion": true,
    "traits": {},
    "linkedinUrl": "<string>",
    "avatarUrl": "<string>",
    "lastSeenAt": "2023-11-07T05:31:56Z",
    "engagementScore": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "archivedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid JSON body",
    "doc_url": "https://docs.gaintrace.com/errors#bad_request"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization header",
    "doc_url": "https://docs.gaintrace.com/errors#unauthorized"
  }
}

{
  "error": {
    "code": "payment_required",
    "message": "Monthly event limit reached. Upgrade or enable overage billing.",
    "doc_url": "https://docs.gaintrace.com/errors#payment_required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient scope: write:companies required",
    "doc_url": "https://docs.gaintrace.com/errors#forbidden"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Company not found",
    "doc_url": "https://docs.gaintrace.com/errors#not_found"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "A contact with this email already exists in the workspace",
    "doc_url": "https://docs.gaintrace.com/errors#conflict"
  }
}

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Request validation failed. name: name is required",
    "doc_url": "https://docs.gaintrace.com/errors#unprocessable_entity"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Can't accept more than 60 requests a minute from one API key. Retry in 23 seconds.",
    "doc_url": "https://docs.gaintrace.com/errors#rate_limit_exceeded"
  }
}

{
  "error": {
    "code": "internal_server_error",
    "message": "Something went wrong. Try again in a moment.",
    "doc_url": "https://docs.gaintrace.com/errors#internal_server_error"
  }
}

{
  "error": {
    "code": "service_unavailable",
    "message": "We had trouble reaching the database. Try again in a moment.",
    "doc_url": "https://docs.gaintrace.com/errors#service_unavailable"
  }
}

{
  "error": {
    "code": "gateway_timeout",
    "message": "The request timed out. Try again in a moment.",
    "doc_url": "https://docs.gaintrace.com/errors#gateway_timeout"
  }
}

People

Create or upsert a person

Adds a Person to a Company.

Name the Company with accountId or accountExternalId.
A Person who already exists at a different Company gets a new record at this one. Matching is by externalId, then email. That does not count against your People limit.
A Person who already exists at this Company fails with 409, unless you send upsert: true. Then the record is updated and returned with 200, and traits are merged.
A new Person counts against your People limit (402 when it is reached).
With accountExternalId, an unknown Company is created for you and counts against your Company limit. It fires the company.created webhook with source set to api. It does not start Company-created Flows.
A new Person fires contact.created, and an upsert that updates a Person fires contact.updated, both with source set to api.

This is the same operation as POST /contacts.

Scope: write:contacts

POST

people

Create or upsert a person

curl --request POST \
  --url https://app.gaintrace.com/api/v1/people \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountExternalId": "acme",
  "accountName": "Acme Inc",
  "name": "Ana Ruiz",
  "email": "[email protected]",
  "externalId": "user_8812",
  "contactRole": "decision_maker",
  "upsert": true,
  "traits": {
    "plan_tier": "growth"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountExternalId: 'acme',
    accountName: 'Acme Inc',
    name: 'Ana Ruiz',
    email: '[email protected]',
    externalId: 'user_8812',
    contactRole: 'decision_maker',
    upsert: true,
    traits: {plan_tier: 'growth'}
  })
};

fetch('https://app.gaintrace.com/api/v1/people', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://app.gaintrace.com/api/v1/people"

payload = {
    "accountExternalId": "acme",
    "accountName": "Acme Inc",
    "name": "Ana Ruiz",
    "email": "[email protected]",
    "externalId": "user_8812",
    "contactRole": "decision_maker",
    "upsert": True,
    "traits": { "plan_tier": "growth" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "[email protected]",
    "externalId": "<string>",
    "phone": "<string>",
    "role": "<string>",
    "contactRole": "decision_maker",
    "isChampion": true,
    "traits": {},
    "linkedinUrl": "<string>",
    "avatarUrl": "<string>",
    "lastSeenAt": "2023-11-07T05:31:56Z",
    "engagementScore": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "archivedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "accountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "name": "<string>",
    "email": "[email protected]",
    "externalId": "<string>",
    "phone": "<string>",
    "role": "<string>",
    "contactRole": "decision_maker",
    "isChampion": true,
    "traits": {},
    "linkedinUrl": "<string>",
    "avatarUrl": "<string>",
    "lastSeenAt": "2023-11-07T05:31:56Z",
    "engagementScore": 123,
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "archivedAt": "2023-11-07T05:31:56Z"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid JSON body",
    "doc_url": "https://docs.gaintrace.com/errors#bad_request"
  }
}

{
  "error": {
    "code": "unauthorized",
    "message": "Missing Authorization header",
    "doc_url": "https://docs.gaintrace.com/errors#unauthorized"
  }
}

{
  "error": {
    "code": "payment_required",
    "message": "Monthly event limit reached. Upgrade or enable overage billing.",
    "doc_url": "https://docs.gaintrace.com/errors#payment_required"
  }
}

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient scope: write:companies required",
    "doc_url": "https://docs.gaintrace.com/errors#forbidden"
  }
}

{
  "error": {
    "code": "not_found",
    "message": "Company not found",
    "doc_url": "https://docs.gaintrace.com/errors#not_found"
  }
}

{
  "error": {
    "code": "conflict",
    "message": "A contact with this email already exists in the workspace",
    "doc_url": "https://docs.gaintrace.com/errors#conflict"
  }
}

{
  "error": {
    "code": "unprocessable_entity",
    "message": "Request validation failed. name: name is required",
    "doc_url": "https://docs.gaintrace.com/errors#unprocessable_entity"
  }
}

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Can't accept more than 60 requests a minute from one API key. Retry in 23 seconds.",
    "doc_url": "https://docs.gaintrace.com/errors#rate_limit_exceeded"
  }
}

{
  "error": {
    "code": "internal_server_error",
    "message": "Something went wrong. Try again in a moment.",
    "doc_url": "https://docs.gaintrace.com/errors#internal_server_error"
  }
}

{
  "error": {
    "code": "service_unavailable",
    "message": "We had trouble reaching the database. Try again in a moment.",
    "doc_url": "https://docs.gaintrace.com/errors#service_unavailable"
  }
}

{
  "error": {
    "code": "gateway_timeout",
    "message": "The request timed out. Try again in a moment.",
    "doc_url": "https://docs.gaintrace.com/errors#gateway_timeout"
  }
}

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

Option 1
Option 2

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

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

The Person already existed at this Company and upsert was true. The updated record.

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.

Show child attributes

Companies

People

Contacts

Signals

Surveys

Survey segments

Survey imports

Survey responses

NPS responses

Ingest

Create or upsert a person

Authorizations

Body

Response