Response Structure - Research Desk Documentation

All endpoints accept and return JSON. The Content-Type header for POST and PATCH requests must be application/json.

Success Responses

Successful requests return HTTP 2xx status codes. The response body contains the requested object or array directly — there is no outer wrapper envelope. Single object example (GET /surveys/):

{
  "id": "abc-123",
  "name": "US Gen Pop Q2 2025",
  "status": "Live",
  "country": "US"
}

List example (GET /surveys):

[
  { "id": "abc-123", "name": "US Gen Pop Q2 2025", ... },
  { "id": "def-456", "name": "UK Millennials", ... }
]

Error Responses

All error responses return a JSON body with a message field containing a human-readable description suitable for display to end users.

Returned when a required field is missing or a field value is invalid.

{
  "message": "Survey name is required."
}

Returned when the Authorization header is missing, expired, or invalid.

{
  "message": "Unauthorized."
}

Returned when the requested resource does not exist or is not accessible under your account.

{
  "message": "Survey could not be found."
}

Returned when an unsupported HTTP method is used — for example, attempting to DELETE a resource.

{
  "message": "Survey objects cannot be deleted."
}

Returned when a rate limit is exceeded. See Rate Limits for per-endpoint limits and retry guidance.

{
  "message": "Too many requests. Please try again later."
}

Returned when an unexpected server-side error occurs. If this persists, contact clientsuccess@repdata.com.

{
  "message": "Our server experienced an unexpected error."
}

HTTP Status Code Reference

Code	Meaning	Common Cause
`200 OK`	Success	Standard success for GET and PATCH
`201 Created`	Resource created	Success for POST (create) requests
`400 Bad Request`	Validation error	Missing required field or invalid value
`401 Unauthorized`	Auth failure	Missing, expired, or invalid token
`404 Not Found`	Resource missing	Wrong ID or insufficient account permissions
`405 Method Not Allowed`	Invalid method	Attempting DELETE or unsupported verb
`429 Too Many Requests`	Rate limited	Request volume exceeded per-endpoint limit
`500 Internal Server Error`	Server error	Unexpected error — contact support if persistent

Pagination

Endpoints that return lists (GET /surveys, GET /responses) support pagination via query parameters:

Parameter	Type	Description
`page`	integer	Page number, starting at `1` (default: `1`)
`page_size`	integer	Number of results per page (default varies by endpoint)

Example: GET /surveys?page=2&page_size=50

When polling for responses during active fieldwork, combine pagination with a timestamp filter where supported to retrieve only new records since your last poll.

​Success Responses

​Error Responses

​HTTP Status Code Reference

​Pagination

Success Responses

Error Responses

HTTP Status Code Reference

Pagination