> ## 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. # Request survey invitations > Request email invitations for up to 100 people (`personIds`), or for everyone a saved segment (`segmentId`) or a set of Company and People rules (`audience`) matches, up to 1,000 people. The survey must be `active`. **Send or approve.** Workspaces send by default: each invitation is released to send right away, or at the survey's next send window. A workspace can switch to approval, where invitations wait in Triage until a teammate approves them, and approvals expire after 14 days. The result's `mode` says which applied. Invitations sent by an API key follow the workspace setting. **Who is skipped.** People are skipped, not failed, when an invitation for their email already waits or is about to send, when they are inside the survey's `cooldownDays`, or when the workspace frequency rule applies. The response counts them but does not name them. To preview who would be invited, use the `gt_survey_request_invitations` MCP tool, which defaults to a dry run. **Errors.** With `personIds`, every person must be active, have an email address and belong to a Company, or the whole request returns `400` and nothing is queued. A `segmentId` that is missing or archived returns `404`. An audience that matches more than 1,000 people returns `400`: narrow the rules or split them into segments. An `audience` with no rules, or a body with more than one of the three keys, returns `422`. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `write:surveys` ## OpenAPI ````yaml /openapi.json post /surveys/{id}/invitations 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: /surveys/{id}/invitations: post: tags: - Surveys summary: Request survey invitations description: >- Request email invitations for up to 100 people (`personIds`), or for everyone a saved segment (`segmentId`) or a set of Company and People rules (`audience`) matches, up to 1,000 people. The survey must be `active`. **Send or approve.** Workspaces send by default: each invitation is released to send right away, or at the survey's next send window. A workspace can switch to approval, where invitations wait in Triage until a teammate approves them, and approvals expire after 14 days. The result's `mode` says which applied. Invitations sent by an API key follow the workspace setting. **Who is skipped.** People are skipped, not failed, when an invitation for their email already waits or is about to send, when they are inside the survey's `cooldownDays`, or when the workspace frequency rule applies. The response counts them but does not name them. To preview who would be invited, use the `gt_survey_request_invitations` MCP tool, which defaults to a dry run. **Errors.** With `personIds`, every person must be active, have an email address and belong to a Company, or the whole request returns `400` and nothing is queued. A `segmentId` that is missing or archived returns `404`. An audience that matches more than 1,000 people returns `400`: narrow the rules or split them into segments. An `audience` with no rules, or a body with more than one of the three keys, returns `422`. Requires a secret server key (`gt_live_`). Publishable keys (`gt_pub_`) return `403`. **Scope:** `write:surveys` operationId: requestSurveyInvitations parameters: - $ref: '#/components/parameters/surveyId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SurveyInvitationRequest' examples: people: summary: Specific people value: personIds: - c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f segment: summary: A saved segment value: segmentId: 3f6a9c1e-8b2d-4c7a-9e5f-0a1b2c3d4e5f audience: summary: Rules value: audience: company: logic: and rules: - field: segment operator: eq value: enterprise person: logic: and rules: - field: contactRole operator: is_any_of value: - decision_maker - champion responses: '202': description: Invitations accepted. content: application/json: schema: type: object required: - data properties: data: $ref: '#/components/schemas/SurveyInvitationResult' example: data: mode: send queued: 0 sending: 38 skipped: 4 batchId: e4b1c2d3-6f7a-4b8c-9d0e-1f2a3b4c5d6e sendAt: null matched: 42 '400': $ref: '#/components/responses/BadRequest' '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: parameters: surveyId: name: id in: path required: true description: The survey's UUID. schema: type: string format: uuid schemas: SurveyInvitationRequest: description: >- Who to invite. Send exactly one of `personIds`, `segmentId` or `audience`. oneOf: - type: object required: - personIds additionalProperties: false properties: personIds: type: array minItems: 1 maxItems: 100 items: type: string format: uuid description: Ids of people. Duplicates are ignored. - type: object required: - segmentId additionalProperties: false properties: segmentId: type: string format: uuid description: A saved segment from `POST /survey-segments`. - type: object required: - audience additionalProperties: false properties: audience: $ref: '#/components/schemas/SurveyAudienceRules' SurveyInvitationResult: type: object required: - mode - queued - sending - skipped - batchId - sendAt properties: mode: type: string enum: - send - approve description: >- The workspace's invitation setting. `send` releases invitations to send. `approve` holds them in Triage until a teammate approves. queued: type: integer description: >- Invitations now waiting for approval in Triage. Always `0` when `mode` is `send`. sending: type: integer description: >- Invitations released to send: right away, or at the survey's next send window. Always `0` when `mode` is `approve`. skipped: type: integer description: >- People left out: an invitation already waits or is about to send for their email, they are inside this survey's `cooldownDays`, or they were surveyed within the workspace frequency rule. batchId: type: string format: uuid sendAt: type: - string - 'null' format: date-time description: >- When released invitations send, if the survey has a send window. `null` when the survey has no send window, or when `mode` is `approve`. matched: type: integer description: >- Only for `segmentId` and `audience` requests: how many people the audience matched before skips. SurveyAudienceRules: type: object required: - company - person additionalProperties: false description: >- Who to reach: People who match `person`, at Companies that match `company`. An empty `rules` list in a group matches everyone for that group. A request needs at least one rule across both groups, so nobody is ever invited by accident. Only People with an email address at Companies that aren't archived can match. properties: company: $ref: '#/components/schemas/SurveyFilterGroup' person: $ref: '#/components/schemas/SurveyFilterGroup' 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. SurveyFilterGroup: type: object required: - logic - rules additionalProperties: false properties: logic: type: string enum: - and - or rules: type: array maxItems: 20 items: $ref: '#/components/schemas/SurveyFilterRule' SurveyFilterRule: type: object required: - field - operator - value additionalProperties: false properties: field: type: string minLength: 1 maxLength: 120 description: >- In a Company rule group, a field key from your Company data model, such as `segment` or `plan`. In a People rule group, one of `email`, `name`, `role`, `contactRole`, `isChampion`, `lastSeenAt`, `engagementScore`, `createdAt`, or `traits.` for a Person trait. `person.` and `people.` prefixes are accepted. Any other People field returns `422`. operator: type: string enum: - eq - neq - gt - gte - lt - lte - contains - not_contains - starts_with - ends_with - is_empty - is_not_empty - in - not_in - between - before - after - in_the_last - in_the_next - older_than - further_than - is - is_not - is_any_of - is_none_of description: The same operators Flow conditions use. value: oneOf: - type: string maxLength: 500 - type: number - type: boolean - type: array maxItems: 50 items: type: string maxLength: 200 value2: oneOf: - type: string maxLength: 500 - type: number description: The upper bound for `between`. unit: type: string enum: - minutes - hours - days - workdays - weeks - months description: The unit for date operators such as `in_the_last`. responses: BadRequest: description: The request could not be parsed (for example, malformed JSON). content: application/json: schema: $ref: '#/components/schemas/Error' example: error: code: bad_request message: Invalid JSON body doc_url: https://docs.gaintrace.com/errors#bad_request 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.