Import an NPS response

curl --request POST \
  --url https://app.gaintrace.com/api/v1/nps-responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "retently",
  "externalId": "resp_4471",
  "score": 9,
  "respondedAt": "2026-10-01T19:50:00+05:30",
  "accountId": "a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33",
  "email": "[email protected]",
  "comment": "Support is quick.",
  "campaignId": "q3-relationship"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'retently',
    externalId: 'resp_4471',
    score: 9,
    respondedAt: '2026-10-01T19:50:00+05:30',
    accountId: 'a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33',
    email: '[email protected]',
    comment: 'Support is quick.',
    campaignId: 'q3-relationship'
  })
};

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

import requests

url = "https://app.gaintrace.com/api/v1/nps-responses"

payload = {
    "provider": "retently",
    "externalId": "resp_4471",
    "score": 9,
    "respondedAt": "2026-10-01T19:50:00+05:30",
    "accountId": "a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33",
    "email": "[email protected]",
    "comment": "Support is quick.",
    "campaignId": "q3-relationship"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "data": {
    "id": "0d5e7a31-92c4-4f0b-8a16-3b7d2c9e4f55",
    "provider": "retently",
    "externalId": "resp_4471",
    "accountId": "a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33",
    "contactId": "4c1d3b0a-5f0e-4b6e-9a53-1f2d7c8e9a10",
    "email": "[email protected]",
    "score": 9,
    "category": "promoter",
    "comment": "Support is quick.",
    "campaignId": "q3-relationship",
    "source": "api:retently",
    "respondedAt": "2026-10-01T14:20:00.000Z"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "<string>",
    "doc_url": "https://docs.gaintrace.com/errors#not_found"
  }
}

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

{
  "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": "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"
  }
}

NPS responses

Import an NPS response

Imports one NPS answer from another survey tool. Send one answer per request. Requires a secret key (gt_live_); a publishable key gets 403.

Idempotent. provider and externalId together identify the answer. Sending the same pair again updates the stored answer instead of adding a second one. The response is 200 either way.
Who answered. Send contactId, or send both accountId and email. With contactId, the Company and email come from that Person. With accountId and email, GainTrace tries to match a Person at that Company and leaves contactId null when it cannot.
Category. GainTrace sets category from score: 9-10 promoter, 7-8 passive, 0-6 detractor.
Stored with your other NPS. The answer is saved with source set to api:<provider>, next to answers collected by GainTrace surveys. A comment is read for themes.
Webhook. A new answer fires survey_response.created. A repeat of an answer you already imported fires survey_response.updated. Imported answers have surveyId: null and channel: import.
No outreach. The import does not send survey emails or follow-up messages.

Scope: write:surveys

POST

nps-responses

Import an NPS response

curl --request POST \
  --url https://app.gaintrace.com/api/v1/nps-responses \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "provider": "retently",
  "externalId": "resp_4471",
  "score": 9,
  "respondedAt": "2026-10-01T19:50:00+05:30",
  "accountId": "a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33",
  "email": "[email protected]",
  "comment": "Support is quick.",
  "campaignId": "q3-relationship"
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    provider: 'retently',
    externalId: 'resp_4471',
    score: 9,
    respondedAt: '2026-10-01T19:50:00+05:30',
    accountId: 'a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33',
    email: '[email protected]',
    comment: 'Support is quick.',
    campaignId: 'q3-relationship'
  })
};

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

import requests

url = "https://app.gaintrace.com/api/v1/nps-responses"

payload = {
    "provider": "retently",
    "externalId": "resp_4471",
    "score": 9,
    "respondedAt": "2026-10-01T19:50:00+05:30",
    "accountId": "a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33",
    "email": "[email protected]",
    "comment": "Support is quick.",
    "campaignId": "q3-relationship"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "data": {
    "id": "0d5e7a31-92c4-4f0b-8a16-3b7d2c9e4f55",
    "provider": "retently",
    "externalId": "resp_4471",
    "accountId": "a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33",
    "contactId": "4c1d3b0a-5f0e-4b6e-9a53-1f2d7c8e9a10",
    "email": "[email protected]",
    "score": 9,
    "category": "promoter",
    "comment": "Support is quick.",
    "campaignId": "q3-relationship",
    "source": "api:retently",
    "respondedAt": "2026-10-01T14:20:00.000Z"
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "<string>",
    "doc_url": "https://docs.gaintrace.com/errors#not_found"
  }
}

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

{
  "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": "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

One NPS answer from another tool. Send contactId, or send both accountId and email. Fields not listed here are rejected.

provider

string

required

The tool the answer came from, for example retently.

Required string length: 1 - 64

Pattern: ^[a-zA-Z0-9_-]+$

externalId

string

required

The answer's id in that tool. With provider, it makes the import idempotent.

Required string length: 1 - 255

score

integer

required

Required range: 0 <= x <= 10

respondedAt

string<date-time>

required

ISO 8601 with a UTC offset.

accountId

string<uuid>

The Company id.

contactId

string<uuid>

The Person id. GainTrace takes the Company and email from this Person.

string<email>

Maximum string length: 254

comment

string

Maximum string length: 5000

campaignId

string

Maximum string length: 255

Response

The stored answer, whether it was new or an update.

data

object

Show child attributes

Companies

People

Contacts

Signals

Surveys

Survey segments

Survey imports

Survey responses

NPS responses

Ingest

Import an NPS response

Authorizations

Body

Response