Version 2

Base url: https://data.hubux.com/api/v2

Headers:

"Authorization": "Token <token>" // Reach out to us for a token "Content-Type": "application/json"

Pagination:

List endpoints return a count of all results and links to the next and previous pages:

{ "count": 300, "next": "<https://data.hubux.com/api/v2/><resource_name_plural>?page=<n+1>", "previous": "<https://data.hubux.com/api/v2/><resource_name_plural>?page=<n-1>", "results": [ ... ] }

We return 100 results per page, but don’t rely on this—it may be changed in a future release.

Characteristics

List	GET /characteristics
Retrieve	GET /characteristics/<characteristic_id>

Example Respondent:

{ "answers": [ { "id": "00000000-0000-0000-0000-000000000000", "other": false, "position": 0, "text": "Example", "user_specified": false } ], "id": "00000000-0000-0000-0000-000000000000", "import_key": "example", "rows": [], // only populated for Characteristics with type GS (grid) "short_name": "Example", "text": "Example", "tenant": null, "type": "SS" /** * Possible values for `type`: * - DT (date) * - GS (grid) * - MS (multi-select) * - NM (number) * - OE (open-ended) * - SS (single select) */ }

Respondents

List	GET /respondents
Retrieve	GET /respondents/<respondent_id>

Example Respondent:

{ "id": "00000000-0000-0000-0000-000000000000", "approval_status": "A", // (approved) — can also be "D" (denied) or "N" (needs review) "approved_on": "1999-12-31T23:59:59.999999Z", "completed_on": "1999-12-31T23:59:59.999999Z", "person": { "panelist": "00000000-0000-0000-0000-000000000000" }, "responses": [ { "id": "00000000-0000-0000-0000-000000000000", "element": "00000000-0000-0000-0000-000000000000", "row": "00000000-0000-0000-0000-000000000000", "selected_answers": [ { "id": "00000000-0000-0000-0000-000000000000", "answer": { "id": "00000000-0000-0000-0000-000000000000", "exclusive": false, "other": false, "position": 0, "rating": null, "text": "example", "user_specified": false }, "custom_answer": "example", "position": 0, "row": "00000000-0000-0000-0000-000000000000", "status": "Q" // (quota) — can also be "T" (terminated) or "OQ" (over quota) } ], "value": "example" } ], "recruitment_source_id": "example", "referrer": "<https://example.com>", "screener": { "study": "00000000-0000-0000-0000-000000000000" } "source_group": "example", "started_on": "1999-12-31T23:59:59.999999Z", "status": "Q" // (quota) — can also be "T" (terminated) or "OQ" (over quota) }

Panelists

List	GET /panelists
Retrieve	GET /panelists/<panelist_id>

Example Panelist:

{ "characteristic_responses": [ { "characteristic": "00000000-0000-0000-0000-000000000000", "responses": [ { "answer": "00000000-0000-0000-0000-000000000000", "characteristic": "00000000-0000-0000-0000-000000000000", "created": "2022-11-16T17:44:04.570399Z", "custom_answer": null, "id": "00000000-0000-0000-0000-000000000000", "modified": "2022-11-16T17:44:04.570399Z", "row": null, "text_value": "Example" } ] } ], "id": "00000000-0000-0000-0000-000000000000", "person": { "id": "00000000-0000-0000-0000-000000000000", "first_name": "Example", "last_name": "Example", "opt_in": true, "opt_out_date": "1999-12-31T23:59:59.999999Z", "respondents": [ { "id": "00000000-0000-0000-0000-000000000000", "screener": { "study": "00000000-0000-0000-0000-000000000000" } } ] } }

Studies

List	GET /studies
Retrieve	GET /studies/<study_id>

Example Study:

{ "id": "00000000-0000-0000-0000-000000000000", "name": "Example", "name_public": "Example", "screener": { "description": "Example", "elements": [ { "id": "00000000-0000-0000-0000-000000000000", "answers": [ { "id": "00000000-0000-0000-0000-000000000000", "exclusive": false, "other": false, "position": 0, "rating": 5, "text": "example", "user_specified": false } ], "characteristic": "00000000-0000-0000-0000-000000000000", "label": "EXMPL", "position": 0, "text": "Example", "type": "SS" /** * Possible values for `type`: * - AV (audition video) * - CM (comment) * - DS (dropdown select) * - DT (date) * - FL (files) * - GS (grid) * - MS (multi-select) * - NM (number) * - OE (open-ended) * - RH (audition text) * - RK (rank items) * - SS (single select) * - VD (video) */ } ], "title": "Example" }, "status": "DR", // (draft) — can also be "LV" (live) or "CM" (completed) "type": "SY", // (survey) — can also be "OO" (1:1 interview) or "SS" (focus group) "start_date": "1999-12-31T23:59:59.999999Z", "completed_on": "1999-12-31T23:59:59.999999Z" }

Version 1

Respondents

List Respondents

https://data.hubux.com/api/v1/respondents

Lists all respondents.

Example (CURL)

curl --location --request GET '<https://data.hubux.com/api/v1/respondents>' \\ --header 'Content-Type: application/json' \\ --header 'Authorization: Token <token>'

Get Respondent

https://data.hubux.com/api/v1/respondents/**<respondent_id>**

Get respondent details by **respondent_id**.

Example (CURL)

curl --location --request GET '<https://data.hubux.com/api/v1/respondents/**><respondent_id>**' \\ --header 'Content-Type: application/json' \\ --header 'Authorization: Token <token>'

Mark Study Complete for Respondent

https://data.hubux.com/s/**<study_id>**/r/**<respondent_id>**/finish/**<quota_flag>**

Completes a study for the given respondent, and assigns **<quota_flag>** as the respondent’s status. Optionally accepts a respondentQuery to update source data.

Props
URL props Required Description <study_id> Yes UUID: • copy from https://www.notion.so/Inbound-Exit-Links-MOVED-1e3bd0ae1310475a91749ed4371c52bb in project settings • retrieve with %study.id% in outgoing exit link <respondent_id> Yes UUID: retrieve with %respondent.id% in outgoing exit link <quota_flag> Yes Status to assign to respondent: • q: Within quota • oq: Over quota • t: Terminated Body props Required Description respondentQuery No object/Record<string, string>: Update r_query as if using query parameters on https://www.notion.so/Inbound-Exit-Links-MOVED-1e3bd0ae1310475a91749ed4371c52bb.
Source info can be set with recruitmentSourceId and sourceGroupId, or with your custom keys e.g. rs_id, sg |

Example (CURL)

curl --location --request POST '<https://data.hubux.com/api/v1/s/**><study_id>**/r/**<respondent_id>**/finish/**<quota_flag>**' \\ --header 'Content-Type: application/json' \\ --header 'Authorization: Token **<token>**' \\ --data '{ "respondentQuery": { "rs_id": "example" } }'

Expected Successful Response

status: 200 body: { "message": "Successfully updated respondent status and query" }

⚠️ Warning: Surveys that expect respondents to be marked complete using this method should enable this option in the project's advanced configuration (see right):

Enable this switch to only mark respondents complete when using the API or Inbound Exit Links (MOVED).

Panelists

Get Panelist Study Responses

https://data.hubux.com/api/v1/panelists/**<panelist_id>**/study/**<study_id>**

Get panelist characteristics and study responses by <panelist_id> and <study_id>

Example (CURL)

curl --location --request GET '<https://data.hubux.com/api/v1/panelists/**><panelist_id>**/study/**<study_id>**' \\ --header 'Content-Type: application/json' \\ --header 'Authorization: Token <token>'

Expected Successful Response

status: 200 body: { "panelist_id": <uuid>, "respondent_id": <uuid>, "characteristics": [ { "id": <uuid | null>, "key": <string>, "type": <"SS" | "MS" | "OE">, "response": <string> }, ], "study_responses": [ { "id": <uuid>, "key": <string>, "type": <"SS" | "MS" | "OE" | "GS" | "AV" | "DS" | "NM" | "RH" | "CM" | "VD">, "response": <string | [{}]> # For Grid questions (GS) this will be a list of responses with id, key and response fields } ] }

Question types are:

SS - single select

MS - multi-select. Responses will be like "answer1 | answer2 | answer3"

OE - open-ended

GS - Grid question. Response will be a list of responses

AV - Audition video. Response will be a url of a video

DS - Drop down select

NM - number

RH - Red Herring. Response will be open text

CM - Comment

VD - Video. Response will be url of a video

Get Panelist

https://data.hubux.com/api/v1/panelists/**<panelist_id>**

Get panelist details by **<panelist_id>**.

Example (CURL)

curl --location --request GET '<https://data.hubux.com/api/v1/panelists/**><panelist_id>**' \\ --header 'Content-Type: application/json' \\ --header 'Authorization: Token <token>'

Update Panelist

https://data.hubux.com/api/v1/panelists/**<panelist_id>**/

Update panelist characteristics by **<panelist_id>**.

The body should contain the characteristic keys and new values for example:

{ "characteristics": { "age": "18-24", "gender": "Male", "favorite_color": "Indigo", "favorite_movie_characters": "Grogu | The Dude | Andy Dufresne" } }

If a characteristic does not exist it will return a 400 - Bad Request error. If a supplied characteristic answer does not exist for a HubUX characteristic it will return a 400 - Bad Request error. If a supplied characteristic answer does not exist for a Tenant characteristic it will return a 400 - Bad Request error.

Multi-select answers should be separated by the pipe character “|”

NOTE: a trailing forward slash '/' is required after the panelist_id

WARNING: Updating Grid characteristic answers is not currently supported via this API route

Example (CURL)

curl --location --request PUT '<https://data.hubux.com/api/v1/panelists/**><panelist_id>**/' \\ --header 'Content-Type: application/json' \\ --header 'Authorization: Token <token>' \\ --data '{ "characteristics": { <characteristic_key: string>: <characteristic_value: string> } }'