Load Survey Page | Take Survey API Reference Document

Get /surveys/{{survey-id}}/take

This functionality is currently released in ALPHA and under testing. BETA release is expected in April 2026.

Example Request


        https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take

The value of environment {{env}} variable depends upon your datacenter. Refer to the Environment page for more details.

Loads the current page of the survey identified by survey-id. On the very first call the server creates a new session, assigns it a UUID, and returns a x-survey-token response header containing a signed token. The next request must send that token back in the x-survey-token request header so the server can identify the session.

Authorization

Session Token — x-survey-token

Name : x-survey-token

required after first call

Location : Request Header

Type : string

Description : Signed session token returned by the server in the x-survey-token response header on every call. Echo it back in the x-survey-token request header on the next request. Do not parse or modify the token — treat it as an opaque string.

Security - API Key

Name : api-key

required

Location : Request Header

Type : string

Request Parameters

Path Parameters

survey-id integer

required

Example Code

cURL

Snippet copied successfully.

application/json


                #  First call — no token yet; server returns x-survey-token in the response headers
                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take' \
                  --header 'Accept: application/json' \
                  --header 'api-key: {{api-key}}'

                #  Subsequent calls — echo back the token from the previous response
                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take' \
                  --header 'Accept: application/json' \
                  --header 'api-key: {{api-key}}' \
                  --header 'x-survey-token: {{x-survey-token}}'

Python

Snippet copied successfully.

application/json


                import requests

                url = "https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take"

                headers = {
                    "Accept": "application/json",
                    "api-key": "{{api-key}}"
                }

                #  First call — no session token yet
                response = requests.get(url, headers=headers)
                data = response.json()

                #  Save the session token from the response header
                session_token = response.headers.get("x-survey-token")

                #  All subsequent calls — send the token back
                headers["x-survey-token"] = session_token
                response = requests.post(base_url + "/submit-page", headers=headers, json={"answers": []})
                session_token = response.headers.get("x-survey-token")  #  refresh token each time

PHP - cURL

Snippet copied successfully.

application/json


<?php

$curl = curl_init();

// First call — no session token
curl_setopt_array($curl, array(
    CURLOPT_URL            => 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HEADER         => true,
    CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST  => 'GET',
    CURLOPT_HTTPHEADER     => array(
        'Accept: application/json',
        'api-key: {{api-key}}'
    ),
));

$response   = curl_exec($curl);
$headerSize = curl_getinfo($curl, CURLINFO_HEADER_SIZE);
$headersRaw = substr($response, 0, $headerSize);
$body       = substr($response, $headerSize);
curl_close($curl);

// Extract x-survey-token from response headers
preg_match('/x-survey-token:\s*(\S+)/i', $headersRaw, $m);
$sessionToken = $m[1] ?? null;

echo $body;

JavaScript (fetch)

Snippet copied successfully.

application/json


// First call — no session token yet
let response = await fetch(
    'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take',
    {
        method: 'GET',
        headers: {
            'Accept': 'application/json',
            'api-key': '{{api-key}}'
        }
    }
);
let sessionToken = response.headers.get('x-survey-token');
let data = await response.json();

// Subsequent calls — echo the token back
response = await fetch(
    'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page',
    {
        method: 'POST',
        headers: {
            'Accept': 'application/json',
            'Content-Type': 'application/json',
            'api-key': '{{api-key}}',
            'x-survey-token': sessionToken
        },
        body: JSON.stringify({ answers: [] })
    }
);
sessionToken = response.headers.get('x-survey-token'); // always refresh after each call

Responses

200 OK — Page loaded successfully

application/json


// Response header returned by the server (echo this back on the next request):
// x-survey-token: eyJ1dWlkIjoiYWJjMTIzIiwicnMiOjAsImlucyI6IiIsInNlYyI6W119.HMAC_SIGNATURE

{
  "response": {
    "status": "success",
    "meta": {
      "isFinalPage": false,
      "progressPercentage": 0
    },
    "navigation": {
      "previousPageUrl": null,
      "nextPageSubmitUrl": "/a/api/v2/surveys/123456/submit-page"
    },
    "themeConfig": {
      "cssUrls": ["https://cdn.questionpro.com/themes/corporate.css"],
      "jsUrls": []
    },
    "questions": [
      {
        "html": "<div class='qstn-row'>...rendered HTML...</div>",
        "json": {
          "id": 10001,
          "type": "U",
          "text": "How satisfied are you with our service?",
          "answers": [
            { "id": 50001, "text": "Very satisfied" },
            { "id": 50002, "text": "Satisfied" },
            { "id": 50003, "text": "Neutral" },
            { "id": 50004, "text": "Dissatisfied" }
          ],
          "formParam": {
            "paramPrefix": "u_",
            "paramIdType": "questionId"
          }
        }
      }
    ]
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

Schema

application/json


// Response header on every call:
// x-survey-token: <signed-token>  — always present; echo back verbatim on the next request

{
  "response": {
    "status": "string — one of: success | validation_errors | authentication_required |
               already_completed | quota_full | survey_complete | terminated |
               survey_closed | survey_paused | survey_suspended |
               language_selection_required | survey_opt_out | redirect | error",
    "redirectUrl": "string | null — present when status is survey_complete, terminated,
                   or redirect; URL to navigate the respondent to (chain survey,
                   panel redirect, or thank-you page)",
    "meta": {
      "isFinalPage": "boolean — true when this is the last page of the survey",
      "progressPercentage": "integer (0–100) — completion progress"
    },
    "navigation": {
      "previousPageUrl": "string | null — null on the first page",
      "nextPageSubmitUrl": "string — URL to POST answers to"
    },
    "themeConfig": {
      "cssUrls": "array of string — stylesheet URLs for the survey theme",
      "jsUrls": "array of string — JavaScript URLs for the survey theme"
    },
    "questions": [
      {
        "html": "string | null — pre-rendered HTML for the question row",
        "json": "string — JSON-encoded section object with question details and formParam metadata"
      }
    ],
    "validationErrors": "array | null — only present when status is validation_errors"
  },
  "requestID": "string — unique request identifier"
}

200 OK — Authentication required

application/json


{
  "response": {
    "status": "authentication_required"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Already completed

application/json


{
  "response": {
    "status": "already_completed"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Quota full

application/json


{
  "response": {
    "status": "quota_full"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Survey complete (no redirect)

application/json


{
  "response": {
    "status": "survey_complete"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Survey complete with redirect (chain survey or panel)

application/json


{
  "response": {
    "status": "survey_complete",
    "redirectUrl": "https://www.questionpro.com/a/TakeSurvey?tt=abc123"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Terminated (data quality or screener)

application/json


{
  "response": {
    "status": "terminated"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Terminated with redirect (panel redirect)

application/json


{
  "response": {
    "status": "terminated",
    "redirectUrl": "https://panel.example.com/complete?status=disqualified&ref=456"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Survey closed / inactive

application/json


{
  "response": {
    "status": "survey_closed"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Language selection required

application/json


{
  "response": {
    "status": "language_selection_required"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

200 OK — Redirect (chain survey or panel)

application/json


{
  "response": {
    "status": "redirect",
    "redirectUrl": "https://www.questionpro.com/a/TakeSurvey?tt=xyz789"
  },
  "requestID": "8012fedc-e8ce-48ae-b800-6q5ce287987a"
}

400 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "BAD_REQUEST",
         "httpStatusCode": 400,
         "id" : "1000",
         "message": "Invalid URL parameters",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

401 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "UNAUTHORIZED",
         "httpStatusCode": 401,
         "id" : "1010",
         "message": "Incorrect API Key",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

403 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "FORBIDDEN",
         "httpStatusCode": 403,
         "id" : "1013",
         "message": "The user does not have permission to access the resource",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

404 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "NOT_FOUND",
         "httpStatusCode": 404,
         "id" : "1040",
         "message": "The resource that you're trying to access doesn't exist",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

500 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "INTERNAL_SERVER_ERROR",
         "httpStatusCode": 500,
         "id" : "1026",
         "message": "We are not able to process your request",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

x-survey-token Reference

How the session token works

The server returns an x-survey-token response header on every API call — GET /take, POST /submit-page, and GET /previous-page.

The client must send the most recent token back as an x-survey-token request header on every subsequent call.

The token is a base64url-encoded JSON payload signed with HMAC-SHA256. Treat it as an opaque string — do not parse or modify it.

Token payload fields: uuid (session identifier), rs (response-set ID; 0 until first page submitted), ins (survey branch position), sec (array of displayed section IDs).

No sticky sessions or JSESSIONID cookies are required. Any node in the cluster can serve subsequent requests. If the receiving node does not hold the session in memory (e.g. after a restart), it reconstructs the session from the database using the rs field.

The token is refreshed on every call. Always use the token from the most recent response — older tokens may carry stale state.

Status Values Reference

All Possible status Values

success

Page loaded — questions array is populated

validation_errors

Page re-shown with validationErrors array (submit-page only)

authentication_required

Survey has a password gate; display a login form

already_completed

Respondent already finished this survey

quota_full

Survey quota reached; no more responses accepted

survey_complete

All pages submitted; redirectUrl is present when a chain survey or panel redirect is configured

terminated

Respondent was terminated (data quality check or screener logic); redirectUrl is present when a panel redirect is configured

survey_closed

Survey is inactive or closed by the owner

survey_paused

Survey is temporarily paused by the owner

survey_suspended

Owner account is suspended

language_selection_required

Multi-language survey awaiting language choice

redirect

External redirect (chain survey or panel); follow redirectUrl

survey_opt_out

Respondent has opted out via panel link

error

Unexpected server-side error

formParam Metadata Reference

Understanding formParam in the questions[].json field

Each question section JSON contains a formParam object that tells you how to construct the POST body for submit-page.

paramPrefix — the parameter name prefix to use (e.g. u_, m_, t_)

paramIdType — whether to append the questionId or answerId to the prefix

Example (UniChoice): paramPrefix=u_, paramIdType=questionId — key is u_10001 with answerId as value

Example (Text): paramPrefix=t_, paramIdType=answerId — key is t_50001 with free-text as value

otherParamPrefix — present when question has an Other option; key is t_{answerId}

Introduction

Organization

Department

User

Folders

Survey

Blocks

Questions

Answers

Email Lists

Email List Addresses

Email Templates

Send Survey

Schedule Invitation

Export Batch

Responses

Datapad

Response Statistics

Images

Webhooks

Take Survey Response

Example Request

Authorization

Request Parameters

Example Code

Responses

x-survey-token Reference

Status Values Reference

formParam Metadata Reference