curl --request POST \
  --url https://app.gaintrace.com/api/v1/surveys/{id}/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "personIds": [
    "c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
  ]
}
'

{
  "data": {
    "mode": "send",
    "queued": 0,
    "sending": 38,
    "skipped": 4,
    "batchId": "e4b1c2d3-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "sendAt": null,
    "matched": 42
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid JSON body",
    "doc_url": "https://docs.gaintrace.com/errors#bad_request"
  }
}

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

Surveys

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

POST

surveys

{id}

invitations

curl --request POST \
  --url https://app.gaintrace.com/api/v1/surveys/{id}/invitations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "personIds": [
    "c3d24e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f"
  ]
}
'

{
  "data": {
    "mode": "send",
    "queued": 0,
    "sending": 38,
    "skipped": 4,
    "batchId": "e4b1c2d3-6f7a-4b8c-9d0e-1f2a3b4c5d6e",
    "sendAt": null,
    "matched": 42
  }
}

{
  "error": {
    "code": "bad_request",
    "message": "Invalid JSON body",
    "doc_url": "https://docs.gaintrace.com/errors#bad_request"
  }
}

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

Path Parameters

string<uuid>

required

The survey's UUID.

Body

application/json

Option 1
Option 2
Option 3

Who to invite. Send exactly one of personIds, segmentId or audience.

personIds

string<uuid>[]

required

Ids of people. Duplicates are ignored.

Required array length: 1 - 100 elements

Response

Invitations accepted.

data

object

required

Show child attributes

Companies

People

Contacts

Signals

Surveys

Survey segments

Survey imports

Survey responses

NPS responses

Ingest

Request survey invitations

Authorizations

Path Parameters

Body

Response