Create an in-app survey session

curl --request POST \
  --url https://app.gaintrace.com/api/v1/surveys/{id}/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contactId": "c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "accountId": "a1f0c2d3-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "parentOrigin": "https://app.example.com",
  "mode": "survey"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contactId: 'c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f',
    accountId: 'a1f0c2d3-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
    parentOrigin: 'https://app.example.com',
    mode: 'survey'
  })
};

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

import requests

url = "https://app.gaintrace.com/api/v1/surveys/{id}/session"

payload = {
    "contactId": "c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "accountId": "a1f0c2d3-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "parentOrigin": "https://app.example.com",
    "mode": "survey"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "data": {
    "eligible": true,
    "embedUrl": "https://app.gaintrace.com/survey/embed/7b6f2c1e-4d3a-4b5c-9e8f-1a2b3c4d5e6f?t=eyJ...&mode=survey&position=bottom",
    "sessionId": "b2c3d4e5-7a8b-4c9d-8e0f-2a3b4c5d6e7f",
    "delayMs": 3000
  }
}

Surveys

Create an in-app survey session

Decide whether to show an in-app survey to a signed-in person, and mint the signed embed URL if so. Call it from your backend, never from a browser: a request that carries an Origin header is refused with 403, and cross-origin preflight requests are refused too. (Browser code uses a signed identity token with the in-app SDK instead. See the in-app SDK guide.) It returns 200 for both outcomes. When the person qualifies you get eligible: true, an embedUrl that is valid for one hour, a sessionId and the configured delayMs. Otherwise you get eligible: false and a reason: disabled (survey not active or in-app collection off), cooldown, recently_dismissed, not_sampled, snoozed, already_seen, minimum_age, minimum_sessions, display_limit, or, when the survey has targeting, page_not_targeted, not_targeted or awaiting_trigger. A survey with page rules needs context.url; without it the reason is page_not_targeted. A person who passes the earlier checks gets one recorded session per UTC day, and those count toward minSessions. parentOrigin must be listed in settings.inApp.allowedOrigins, or the call returns 403. The person must exist, be active and belong to accountId, or the call returns 404. Send subject to tie the survey to a deal, ticket, plan or custom record; a record GainTrace can’t link returns 422. Any invalid or malformed body, or an invalid survey id, returns 422. Requires a secret server key (gt_live_). Publishable keys (gt_pub_) return 403.

Scope: write:surveys

POST

surveys

{id}

session

Create an in-app survey session

curl --request POST \
  --url https://app.gaintrace.com/api/v1/surveys/{id}/session \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "contactId": "c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
  "accountId": "a1f0c2d3-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "parentOrigin": "https://app.example.com",
  "mode": "survey"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    contactId: 'c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f',
    accountId: 'a1f0c2d3-5e6f-4a7b-8c9d-0e1f2a3b4c5d',
    parentOrigin: 'https://app.example.com',
    mode: 'survey'
  })
};

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

import requests

url = "https://app.gaintrace.com/api/v1/surveys/{id}/session"

payload = {
    "contactId": "c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "accountId": "a1f0c2d3-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
    "parentOrigin": "https://app.example.com",
    "mode": "survey"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "data": {
    "eligible": true,
    "embedUrl": "https://app.gaintrace.com/survey/embed/7b6f2c1e-4d3a-4b5c-9e8f-1a2b3c4d5e6f?t=eyJ...&mode=survey&position=bottom",
    "sessionId": "b2c3d4e5-7a8b-4c9d-8e0f-2a3b4c5d6e7f",
    "delayMs": 3000
  }
}

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.

Path Parameters

string<uuid>

required

The survey's UUID.

Body

application/json

Field names follow the code: contactId is a person id and accountId is a company id.

contactId

string<uuid>

required

The signed-in person's id in GainTrace.

accountId

string<uuid>

required

The id of that person's company. It must match the person.

parentOrigin

string<uri>

required

The exact origin of the page that will show the survey, such as https://app.example.com. It must be listed in the survey's settings.inApp.allowedOrigins.

Maximum string length: 255

mode

enum<string>

default:survey

test skips eligibility rules and records nothing, so you can preview the survey.

Available options:

survey,

test

context

object

What the person is doing right now. Send it when the survey has page rules or a trigger under settings.inApp.targeting.

Show child attributes

subject

object

The deal, ticket, plan or custom record this survey asks about. Responses to the embed carry it as their subject. The record must belong to the same Company as the person. The record a response is about: a deal, ticket, plan or custom record. Name it by its GainTrace id, or, for a deal or ticket, by the id it has in your CRM or help desk (externalId, with source when more than one connection holds that id). For a custom record, send the data model's model slug and the record's externalId. The record must exist, must not be archived, and must belong to the same Company as the person.

Option 1
Option 2
Option 3

Show child attributes

lang

string

A language tag such as es or pt-BR. The survey shows in this language when it has a translation for it. It wins over the person's locale or language trait and the browser.

Maximum string length: 35

Response

The session decision.

data

object

required

Option 1
Option 2

Show child attributes

Companies

People

Contacts

Signals

Surveys

Survey segments

Survey imports

Survey responses

NPS responses

Ingest

Create an in-app survey session

Authorizations

Path Parameters

Body

Response