Field Operations API
Field operations cover everything related to data collection: waves (collection periods), distribution links, respondent invitations, and quota management.
Waves
Waves represent data collection periods within a survey.
List Waves
GET /api/surveys/waves?workspace_id={id}
Wave Progress
GET /api/surveys/waves/progress
Returns progress and quota completion for all active waves.
Wave Count
GET /api/surveys/waves/count
Active Waves by Survey
GET /api/surveys/waves/active-by-survey
Create Wave
POST /api/surveys/waves
| Field | Type | Required | Description |
|---|---|---|---|
survey_id |
integer | Yes | Survey ID |
wave_name |
string | Yes | Wave name |
wave_start_date |
string | No | Start date (ISO 8601) |
wave_end_date |
string | No | End date (ISO 8601) |
Update Wave
PUT /api/surveys/waves/:id
Update Quotas
PATCH /api/surveys/waves/:id/quotas
Wave Distributions
GET /api/surveys/waves/distributions
Quota Rules
GET /api/surveys/waves/quota-rules
Distribution Links
Links are the mechanism for sharing surveys with respondents.
List All Links
GET /api/surveys/links
List Survey Links
GET /api/surveys/:surveyId/links
Create Links
POST /api/surveys/:surveyId/links
| Field | Type | Description |
|---|---|---|
link_type |
string | open, unique, panel |
link_name |
string | Link label |
link_quota |
integer | Max responses for this link |
Update Link
PUT /api/surveys/:surveyId/links/:linkId
Delete Link
DELETE /api/surveys/:surveyId/links/:linkId
Batch Link Actions
POST /api/surveys/links/batch
Perform batch operations on multiple links.
Invitations
Bulk Invite
POST /api/surveys/:surveyId/invite
Send survey invitations to a list of respondents via email.
| Field | Type | Description |
|---|---|---|
respondents |
array | List of {email, name} objects |
link_id |
integer | Distribution link to use |
subject |
string | Email subject |
message |
string | Email body |
Invite Summary
GET /api/surveys/:surveyId/invite/summary
Resend Invitation
POST /api/surveys/:surveyId/invite/:linkId/resend
Respondents
List Respondents
GET /api/surveys/respondents
Get Respondent
GET /api/surveys/respondents/:respondentId
Respondent Count
GET /api/surveys/respondents/count
Create Respondent
POST /api/surveys/respondents
Update Respondent
PUT /api/surveys/respondents/:respondentId
Delete Respondent
DELETE /api/surveys/respondents/:respondentId
Quality Settings
PUT /api/surveys/:id/quality-settings
Configure quality control rules for a survey (speeder thresholds, straightliner detection, duplicate IP blocking).