Record a survey response
Record an answer that your own app, bot or form collected from a known person. It runs the same validation, attribution and follow-through as an emailed survey: the response appears in the inbox, fires signals and Flows, and sends the survey_response.created webhook with channel set to api. Send subject to tie the answer to a deal, ticket, plan or custom record. The survey must be active; otherwise the call returns 404. Re-sending the same externalId for the same survey is safe: the first response is returned with duplicate: true and 200, and the new body is ignored. The first call returns 201. On an anonymous survey the response is stored without a person or company. Answers that don’t fit the survey’s questions, and a subject GainTrace can’t link, return 422. A body that fails its own field schema also returns 422. Requires a secret server key (gt_live_). Publishable keys (gt_pub_) return 403.
Scope: write:surveys
Authorizations
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
The survey's UUID.
Body
An active person in your workspace.
Your own stable id for this answer. Re-sending it for the same survey returns the first response instead of creating another.
1 - 255The first question's score. It must sit inside that question's scale, and must match answers.q0 when you send both.
0 <= x <= 10Answers keyed by zero-based question index: q0, q1 and so on. A score is an integer inside the question's scale. A multiple choice or dropdown answer is one of the listed options. A checkbox answer is a list of options. A ranking is every option, in your order. A matrix is an object of row to column. A date is YYYY-MM-DD. A consent answer is true. Text answers are at most 5,000 characters. Required questions that are visible must be answered. comment carries a free-text comment.
Values for the survey's hiddenFields. At most 10 keys, each name at most 40 characters. Names the survey does not list are dropped.
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
Response
This externalId was already recorded. The first response is returned.