Skip to main content

List accessible surveys

GET 

/api/v2/users/surveys

Returns the surveys (data sources) the caller can query.

A survey's code is the {surveyCode} path parameter of every survey-scoped endpoint: variables, carriers, tree queries, tables, rankings, evaluations, Reach, response curves and optimizations.

What is included​

  • Only surveys enabled in the user's TOM profile and currently available. Surveys that are being loaded or are disabled are left out, so the list can change between calls.
  • Sorted by creation date, oldest first.
  • updatedDate is an empty string, not a date, when the date of the last update is not known.
  • availableReach tells whether the survey is a consumption-diary survey. Only those support Reach: check the flag before calling GET /api/v2/survey/{surveyCode}/reach-capabilities or POST /api/v2/reach/{surveyCode}.
  • weights lists the weightings of the survey in the platform's order, the same ones that GET /api/v2/survey/{surveyCode}/weeks-and-weights returns. The default one has isDefault: true. The list is empty when the survey has no weightings.

Survey names​

  • description is the name you see for the survey in TOM: your own alias for it, else its default alias, else its catalog name. Use it to show the survey.
  • originalDescription is always the catalog name, with no alias. Use it to classify or search surveys.
  • Names are not unique and can change; a new alias can take up to an hour to show. Identify a survey by code.

The list is not paginated. Treat it as a catalog: cache it for the session and refresh it when a survey-scoped call reports that a survey is not available.

Errors​

StatuserrorCodeWhen
400TW_ERR_500The X-API-Key value does not identify a TOM user.
401E401The X-API-Key header is missing or empty.
500GEN_ERR_500Unexpected error.

Responses​

Surveys the caller can query, oldest first.