Responses API

These endpoints let external systems check whether contacts have completed a survey, without needing to export full response data.

Get Responses by Contacts

Look up survey response status for specific contacts. Returns per-contact status including whether the survey was sent, started, or completed.

Endpoint: GET /api/surveys/{surveyId}/responses/by-contacts

Request

{
  "surveyId": "SURVEY_UUID",
  "externalIds": ["PAT-12345", "PAT-67890"]
}

Field	Type	Required	Description
surveyId	UUID	Yes	Survey ID (in URL path)
contactIds	UUID[]	No*	Up to 100 contact IDs
externalIds	string[]	No*	Up to 100 external IDs
status	string	No	Filter by response status (in_progress, complete)

*Provide at least one of contactIds or externalIds. Both can be provided simultaneously.

Response

{
  "results": [
    {
      "contactId": "0195e3a1-...",
      "externalId": "PAT-12345",
      "email": "john.doe@example.com",
      "responseId": "0195e3a1-...",
      "status": "complete",
      "completedAt": "2026-03-05T14:30:00.000Z",
      "personalLinkCode": "aBcDeFgH"
    },
    {
      "contactId": "0195e3a1-...",
      "externalId": "PAT-67890",
      "email": "jane.smith@example.com",
      "responseId": null,
      "status": "not_sent",
      "completedAt": null,
      "personalLinkCode": null
    }
  ]
}

Status Values

Both endpoints use the same status values:

Status	Description
not_sent	Contact exists but no distribution was sent for this survey
sent	Distribution sent, survey not yet opened
in_progress	Respondent has started but not yet submitted
complete	Survey response has been submitted

When a contact has multiple distributions for the same survey, the most recent distribution’s status is returned.

---

Bulk Response Status

Lightweight bulk status check optimized for large batches. Uses a single optimized SQL query for up to 1,000 externalIds.

Endpoint: GET /api/surveys/{surveyId}/responses/bulk-status

Request

{
  "surveyId": "SURVEY_UUID",
  "externalIds": ["PAT-001", "PAT-002", "PAT-003"]
}

Field	Type	Required	Description
surveyId	UUID	Yes	Survey ID (in URL path)
externalIds	string[]	Yes	1–1,000 external IDs to check

Response

{
  "results": [
    {
      "externalId": "PAT-001",
      "status": "complete",
      "completedAt": "2026-03-05T14:30:00.000Z"
    },
    { "externalId": "PAT-002", "status": "sent", "completedAt": null },
    { "externalId": "PAT-003", "status": "not_sent", "completedAt": null }
  ]
}

When a contact has multiple distributions for the same survey, the most advanced status is returned (e.g., complete takes priority over sent).

External IDs not found in the system are returned with status: "not_sent".

---

Export Responses

For full response data (answers, metadata, scores), use the existing export endpoint:

Endpoint: GET /api/surveys/{surveyId}/responses/export

Supports CSV and XLSX formats with filtering by date range, status, and more. See the interactive API docs at /api/docs/survey for full parameter details.