Load Survey Page | Take Survey API Reference Document

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

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 servlet container creates a new HttpSession and returns a Set-Cookie: JSESSIONID= header. Every subsequent request must carry that cookie so the load balancer routes the respondent to the same server (sticky session) and the session state is preserved.

If a session already exists (cookie present) the API resumes from wherever the respondent left off — no parameters required.

Authorization

Session Cookie — JSESSIONID

Name : JSESSIONID

required after first call

Location : Cookie header

Type : string

Description : Set automatically by the server on the first GET /take call. Must be forwarded on all subsequent requests to maintain survey session state.

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


curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take' \
--header 'Accept: application/json' \
--header 'Cookie: JSESSIONID={{jsessionid}}'

Python

Snippet copied successfully.

application/json


import requests

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

headers = {
    "Accept": "application/json"
}

#  On first call, do not pass cookies — the server will set JSESSIONID.
#  On subsequent calls, pass the cookie from the previous response:
#    cookies = {"JSESSIONID": "<value-from-set-cookie-header>"}
session = requests.Session()
response = session.get(url, headers=headers)

print(response.text)
#  The session object automatically stores and forwards the JSESSIONID cookie.

PHP - cURL

Snippet copied successfully.

application/json


<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL            => 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING       => '',
  CURLOPT_MAXREDIRS      => 10,
  CURLOPT_TIMEOUT        => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION   => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST  => 'GET',
  CURLOPT_HTTPHEADER     => array(
    'Accept: application/json',
    'Cookie: JSESSIONID={{jsessionid}}'
  ),
  CURLOPT_COOKIEFILE     => '/tmp/cookie.txt',  // persist JSESSIONID across requests
  CURLOPT_COOKIEJAR      => '/tmp/cookie.txt',
));

$response = curl_exec($curl);
curl_close($curl);
echo $response;

JavaScript (fetch)

Snippet copied successfully.

application/json


const response = await fetch(
  'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/take',
  {
    method: 'GET',
    headers: { 'Accept': 'application/json' },
    credentials: 'include'   // forwards JSESSIONID cookie automatically
  }
);
const data = await response.json();
console.log(data);

Responses

200 OK — Page loaded successfully

application/json


{
  "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": "...rendered HTML for the question...",
        "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

{
  "$schema": "http://json-schema.org/draft-06/schema# ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "navigation": {
          "type": "object",
          "properties": {
            "previousPageUrl": {
              "type": "string"
            },
            "nextPageSubmitUrl": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "previousPageUrl",
            "nextPageSubmitUrl"
          ]
        },
        "redirectUrl": {
          "type": "string"
        },
        "meta": {
          "type": "object",
          "properties": {
            "isFinalPage": {
              "type": "string"
            },
            "progressPercentage": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "isFinalPage",
            "progressPercentage"
          ]
        },
        "questions": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "json": {
                "type": "string"
              },
              "html": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "json",
              "html"
            ]
          }
        },
        "validationErrors": {
          "type": "string"
        },
        "themeConfig": {
          "type": "object",
          "properties": {
            "jsUrls": {
              "type": "string"
            },
            "cssUrls": {
              "type": "string"
            }
          },
          "additionalProperties": false,
          "required": [
            "jsUrls",
            "cssUrls"
          ]
        },
        "status": {
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "navigation",
        "redirectUrl",
        "meta",
        "questions",
        "validationErrors",
        "themeConfig",
        "status"
      ]
    },
    "requestID": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "response",
    "requestID"
  ]
}

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 (all pages submitted)

application/json


{
  "response": {
    "status": "survey_complete"
  },
  "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"
}

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"
  ]
}

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

Survey fully submitted; redirectUrl points to thank-you page

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

Intermediate redirect (survey chain 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

Status Values Reference

formParam Metadata Reference