> ## Documentation Index > Fetch the complete documentation index at: https://docs.gaintrace.com/llms.txt > Use this file to discover all available pages before exploring further. # 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:`, 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` ## OpenAPI ````yaml /openapi.json post /nps-responses openapi: 3.1.0 info: title: GainTrace API version: 1.0.0 description: >- The GainTrace REST API (v1). Read your customer data and push product-usage events, metric events, and signals into GainTrace. All endpoints are authenticated with a Bearer API key and scoped to a single workspace. Each API key can send 60 requests a minute. A `429` response includes a `Retry-After` header with the seconds to wait. servers: - url: https://app.gaintrace.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Companies description: Read and manage canonical company records. - name: Signals description: Read, create, and manage buyer / risk signals. - name: Ingest description: Push product-usage and metric events into GainTrace. - name: Contacts description: >- The original path for People. It shares its handlers with /people, and also offers delete-by-key. - name: Webhooks description: Subscribe to workspace events with signed, retried delivery. - name: People description: Read and manage People. One Person can belong to many Companies. - name: NPS responses description: Import NPS scores from another survey tool and read your NPS history. - name: Surveys description: >- Create and launch surveys, request invitations, record responses and mint in-app sessions. - name: Survey responses description: Read the responses collected by your surveys. - name: Survey segments description: Save groups of Companies and People that surveys can target. - name: Survey imports description: Pull responses from the survey tools your workspace has connected. paths: /nps-responses: post: tags: - NPS responses summary: Import an NPS response description: >- 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:`, 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` operationId: importNpsResponse requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NpsResponseImport' example: provider: retently externalId: resp_4471 score: 9 respondedAt: '2026-10-01T19:50:00+05:30' accountId: a1f0c2d4-7b3e-4e21-8c55-0d9a6b1f2e33 email: ana@acme.com comment: Support is quick. campaignId: q3-relationship responses: '200': description: The stored answer, whether it was new or an update. content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/NpsResponse' example: 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: ana@acme.com score: 9 category: promoter comment: Support is quick. campaignId: q3-relationship source: api:retently respondedAt: '2026-10-01T14:20:00.000Z' '400': description: >- The `contactId` does not match the `accountId` or `email` you sent, or the request was not valid JSON. content: application/json: schema: $ref: '#/components/schemas/Error' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' components: schemas: NpsResponseImport: type: object required: - provider - externalId - score - respondedAt additionalProperties: false description: >- One NPS answer from another tool. Send `contactId`, or send both `accountId` and `email`. Fields not listed here are rejected. properties: provider: type: string minLength: 1 maxLength: 64 pattern: ^[a-zA-Z0-9_-]+$ description: The tool the answer came from, for example `retently`. externalId: type: string minLength: 1 maxLength: 255 description: >- The answer's id in that tool. With `provider`, it makes the import idempotent. score: type: integer minimum: 0 maximum: 10 respondedAt: type: string format: date-time description: ISO 8601 with a UTC offset. accountId: type: string format: uuid description: The Company `id`. contactId: type: string format: uuid description: >- The Person `id`. GainTrace takes the Company and email from this Person. email: type: string format: email maxLength: 254 comment: type: string maxLength: 5000 campaignId: type: string maxLength: 255 NpsResponse: type: object properties: id: type: string format: uuid provider: type: - string - 'null' externalId: type: - string - 'null' description: The id the answer has in the provider's tool. accountId: type: string format: uuid description: The Company `id`. contactId: type: - string - 'null' format: uuid description: The Person `id`, when GainTrace could attribute the answer to one. email: type: string format: email score: type: integer minimum: 0 maximum: 10 category: type: string enum: - promoter - passive - detractor description: Promoter is 9-10, passive is 7-8, detractor is 0-6. comment: type: - string - 'null' campaignId: type: - string - 'null' source: type: - string - 'null' description: '`api:` for imported answers.' respondedAt: type: - string - 'null' format: date-time Error: type: object required: - error description: The standard error envelope. Every 4xx/5xx response uses this shape. properties: error: type: object required: - code - message properties: code: type: string enum: - bad_request - unauthorized - payment_required - forbidden - not_found - conflict - unprocessable_entity - rate_limit_exceeded - internal_server_error - service_unavailable - gateway_timeout description: >- Stable, machine-readable error code. Each code maps to exactly one HTTP status. message: type: string description: >- Human-readable, safe description of what went wrong. Never contains internal or provider detail. doc_url: type: string format: uri example: https://docs.gaintrace.com/errors#not_found description: Deep link to this code in the Errors reference. responses: Unauthorized: description: Missing, malformed, expired, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unauthorized message: Missing Authorization header doc_url: https://docs.gaintrace.com/errors#unauthorized Forbidden: description: >- The key is valid but lacks the required scope, the origin is not allowed, or API v1 is not enabled for the workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: forbidden message: 'Insufficient scope: write:companies required' doc_url: https://docs.gaintrace.com/errors#forbidden NotFound: description: >- The resource, or a resource you referenced, was not found in this workspace. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: not_found message: Company not found doc_url: https://docs.gaintrace.com/errors#not_found UnprocessableEntity: description: The request was well-formed but a value failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: unprocessable_entity message: 'Request validation failed. name: name is required' doc_url: https://docs.gaintrace.com/errors#unprocessable_entity RateLimited: description: >- The per-key rate limit was exceeded. Each API key can send 60 requests per minute, counted in calendar-minute windows. The `Retry-After` header gives the whole seconds (1 to 60) until the next window opens. Wait that long, then retry. headers: Retry-After: description: Whole seconds until the next one-minute window starts. schema: type: integer minimum: 1 maximum: 60 example: 23 content: application/json: schema: $ref: '#/components/schemas/Error' example: 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 InternalServerError: description: >- An unexpected error occurred on our side. The failure is logged; retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: internal_server_error message: Something went wrong. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#internal_server_error ServiceUnavailable: description: >- A backing service (for example, the database) was temporarily unavailable. Retry shortly. content: application/json: schema: $ref: '#/components/schemas/Error' example: 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 GatewayTimeout: description: >- The request took too long upstream before completing. Retry, and reduce batch size for large payloads. content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: gateway_timeout message: The request timed out. Try again in a moment. doc_url: https://docs.gaintrace.com/errors#gateway_timeout securitySchemes: bearerAuth: type: http scheme: bearer description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.