Surveys API

​

Before you start

• Every Surveys endpoint needs a secret key (gt_live_). Publishable keys (gt_pub_) are refused with 403.
• Reading needs the read:surveys scope. Creating, editing, launching, inviting, recording and changing rules need write:surveys. See Authentication.
• Lists use limit (default 50, max 100) and offset. There is no cursor.
• Each key can make 60 requests per minute. Past that, the API returns 429 with the code rate_limit_exceeded. Back off and retry.
• Errors use the standard envelope. A body that isn’t valid JSON is 400. A value that fails its own field’s validation is 422. Rules that compare several fields are different: on PATCH /surveys/{id} and when you launch a survey, a failure (a missing first question, an NPS scale outside 0-10, a CSAT or CES scale outside 1-5 or 1-7, promotional copy, showWhen rules) returns 400 bad_request with a generic message and no field detail. Answers that don’t fit their questions, or a subject that can’t be linked, on POST /surveys/{id}/responses are 422. The session endpoint returns 422 for any invalid or malformed body. Rules the survey enforces, such as editing locked questions, are 400. See Errors.

​

Measures and scales

​

Bands

​

Survey lifecycle

​

What you can still change

​

Channels

​

Record responses from your own system

curl -X POST "https://app.gaintrace.com/api/v1/surveys/$SURVEY_ID/responses" \
  -H "Authorization: Bearer $GAINTRACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personId": "c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "externalId": "ticket-48213-csat",
    "score": 5,
    "answers": { "q1": "Quick and helpful." }
  }'

• The survey must be active. A draft or closed survey returns 404.
• personId must be an active person in your workspace.
• answers are keyed by question index: q0, q1 and so on. Required questions that are visible must be answered, and each value must fit its question.
• score is the first question’s score. If you also send answers.q0, the two must match.
• hidden is an optional object of hidden-field values, such as { "plan": "pro" }. Only names the survey lists in hiddenFields are saved.
• subject is an optional record the answer is about. See Link a response to a record.

​

Idempotency

​

Link a response to a record

• the body of POST /surveys/{id}/responses
• the body of POST /surveys/{id}/session, for an in-app survey
• the subject claim of a signed in-app token (see In-app survey SDK)

​

Invitations and approval

• Send (the default). Invitations go out at once, or at the survey’s next allowed hour if it has a sendWindow.
• Approve. Each invitation joins the Triage approval queue. A teammate approves it, and only then does the email go out. Approvals expire after 14 days.

• An invitation for the same email is already waiting, scheduled or just released.
• The person is inside the survey’s cooldownDays. That counts the last survey of the same measure they got: an email sent, an invited answer or an in-app view.
• The person was surveyed within the workspace frequency rule.

{
  "data": {
    "mode": "send",
    "queued": 0,
    "sending": 41,
    "skipped": 9,
    "batchId": "d1c9a7e4-6b2f-4a3d-9c8e-5f4a3b2c1d0e",
    "sendAt": null
  }
}

​

Target people with segments

• GET /survey-segments lists the workspace’s segments.
• POST /survey-segments saves one and returns 201. Send a name (unique in the workspace, ignoring case) and rules, an object with a company group and a person group. Each group has a logic of and or or and up to 20 rules. At least one rule is required.
• DELETE /survey-segments/{id} archives a segment and returns 204. Surveys that still point at it stop matching anyone.

curl -X POST "https://app.gaintrace.com/api/v1/survey-segments" \
  -H "Authorization: Bearer $GAINTRACE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enterprise champions",
    "rules": {
      "company": { "logic": "and", "rules": [] },
      "person": {
        "logic": "and",
        "rules": [{ "field": "isChampion", "operator": "eq", "value": true }]
      }
    }
  }'

​

Frequency and follow-up rules

​

Frequency rule

​

Response rules

​

Webhooks

​

Read results

• GET /survey-responses lists responses from every native survey, newest first. Filter by surveyId, companyId, measure, band, status (new, in_progress, resolved, open meaning not resolved, or overdue meaning open past your hours-to-close rule), theme, subjectType with subjectId, and a from and to window on submission time. Filters combine, and an unknown parameter returns 422.
• theme limits the list to responses whose written feedback was tagged with one of 14 themes: onboarding, reliability, performance, usability, missing_functionality, integrations, support_quality, documentation, pricing_value, billing_admin, security_compliance, account_management, reporting_analytics or mobile.
• GET /survey-responses/{id} reads one response.
• GET /surveys and GET /surveys/{id} read survey definitions and status.

​

Company scores and coverage

• GET /surveys/rollup-rules and PUT /surveys/rollup-rules read and set that rule: each person’s latest answer, or the mean or median of their answers, inside windowDays, with optional roleWeights for decision makers, executive sponsors and champions.
• GET /companies/{id}/survey-scores returns one Company’s scores under the rule, how many people each rests on, whether a decision maker answered, and a method sentence to show beside the numbers.
• GET /surveys/coverage returns who you hear from: Companies and ARR with a scored answer in the window, at how many a decision maker answered, and Companies renewing in the next 90 days with no feedback in 180 days. ARR is in the workspace reporting currency; currencies with no exchange rate yet are listed in unconvertedCurrencies and left out.

​

Survey templates

​

Logic, jumps and endings

• logic is { "match": "all" | "any", "conditions": [...] } with 1 to 10 conditions. A condition is either an earlier answer, { "question", "operator", "value" }, or a hidden field, { "hidden", "operator": "is" | "is_not", "value" }. Answer operators are lte, gte, eq, is, is_not, includes, excludes, before, after and band. Don’t send logic and showWhen together.
• jumps is up to 10 rules, each { "when": <logic group>, "to": { "question": n } | { "ending": id } | { "end": true } }. The first matching rule wins.
• settings.endings is up to 10 entries with id, name, and optional title, message and link.
• libraryId links a question to the workspace question library.

​

Languages

• settings.defaultLanguage is one of 44 language codes, such as en, fr, de, pt-BR, zh-TW or ar. Without it, the default is English.
• settings.translations is an object keyed by language code, with up to 15 entries. The default language’s entry holds only ui overrides.

{
  "settings": {
    "defaultLanguage": "en",
    "translations": {
      "fr": {
        "title": "Votre avis compte",
        "questions": [
          { "text": "Quelle est la probabilité que vous nous recommandiez ?" },
          null,
          { "text": "Qu'est-ce qui pourrait être amélioré ?" }
        ],
        "thankYou": { "title": "Merci", "message": "Votre réponse a bien été enregistrée." }
      }
    }
  }
}

1. The language the request asks for: the ?lang= parameter on the survey link, such as /survey/{id}?lang=fr, or lang in an in-app session request.
2. The person’s locale trait, then their language trait, on personal links, in-app surveys and email.
3. The browser’s language.
4. The survey’s defaultLanguage.

​

AI follow-up question

​

Import from other survey tools

• GET /survey-imports lists connected sources. Each has id, provider, name, externalSurveyId, measure, scaleMin, scaleMax, status (active, paused or error), credentialHint, connectedAt, lastRunAt, lastSuccessAt, lastError, nextRunAt and lastRun (imported, updated and skipped counts, or null). It needs read:surveys.
• POST /survey-imports/{id}/runs pulls one source now, for up to 60 seconds, and needs write:surveys. It returns 404 for an unknown id, and 409 while another pull is running or when the source’s credential was rejected.

{
  "data": {
    "runId": "9a3f6c1d-2b4e-4d5a-8c7b-1e2f3a4b5c6d",
    "status": "succeeded",
    "fetched": 120,
    "imported": 96,
    "updated": 4,
    "unchanged": 12,
    "skipped": 8,
    "skip_reasons": [{ "reason": "No Company matched the respondent email. Sync or import the Company first.", "count": 8 }],
    "error": null
  }
}

​

Bulk export to your warehouse

​

Next steps