Submit Survey Page | Take Survey API Reference Document

Post /surveys/{{survey-id}}/submit-page

Example Request


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

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

Submits the respondent's answers for the current page and returns the next page (or a final status). The request body is a flat JSON object whose keys are derived directly from the formParam metadata embedded in each question's JSON on the previous GET /take response.

A valid JSESSIONID cookie must be present. The cookie is set automatically by the server when the respondent first calls GET /take.

Authorization

Session Cookie — JSESSIONID

Name : JSESSIONID

required

Location : Cookie header

Type : string

Description : Obtained from the Set-Cookie header of the GET /take response. Must be forwarded on every subsequent request.

Security - API Key

Name : api-key

required

Location : Request Header

Type : string

Request Parameters

Path Parameters

survey-id integer

required

Request Body

Flat formParam JSON object

Content-Type: application/json

The body is a flat JSON object. Each key is constructed from the formParam metadata found in the questions[].json field of the GET /take response.

Key construction rule: <paramPrefix> + <questionId or answerId depending on paramIdType>

UniChoice (paramPrefix=u_, paramIdType=questionId): 'u_{questionId}': '{answerId}'

MultiChoice (paramPrefix=m_, paramIdType=questionId): 'm_{questionId}': ['{answerId1}', '{answerId2}']

Text / Open-ended (paramPrefix=t_, paramIdType=answerId): 't_{answerId}': 'free text value'

Rank Order (paramPrefix=r_, paramIdType=answerId): 'r_{answerId}': '{rank position integer}'

Constant Sum (paramPrefix=s_, paramIdType=answerId): 's_{answerId}': '{numeric value}'

Date (day/month/year): 'dt_day_{answerId}', 'dt_month_{answerId}', 'dt_year_{answerId}'

Date+Time: additionally 'dt_hr_{answerId}', 'dt_min_{answerId}', 'dt_ampm_{answerId}'

Calendar: 'dt_cal_{answerId}': 'YYYY-MM-DD'

Other option text (otherParamPrefix=t_, otherParamIdType=answerId): 't_{otherAnswerId}': 'other text'

Example — UniChoice

application/json


                {
                  "u_10001": "50002"
                }

Example — MultiChoice

application/json


                {
                  "m_10002": ["60001", "60003"]
                }

Example — Text / Open-ended

application/json


                    {
                       "t_70001": "This is my open-ended response"
                    }

Example — UniChoice with Other option

application/json


                {
                  "u_10001": "50099",
                  "t_50099": "Other — please specify: My custom answer"
                }

Example — Rank Order

application/json


                {
                  "r_60001": "1",
                  "r_60002": "3",
                  "r_60003": "2"
                }

Example — Constant Sum

application/json


                {
                  "s_80001": "40",
                  "s_80002": "35",
                  "s_80003": "25"
                }

Example — Date (day/month/year)

application/json


                {
                  "dt_day_90001": "15",
                  "dt_month_90001": "6",
                  "dt_year_90001": "2024"
                }

Example — DateTime (date + time)

application/json


                {
                  "dt_day_90001": "15",
                  "dt_month_90001": "6",
                  "dt_year_90001": "2024",
                  "dt_hr_90001": "10",
                  "dt_min_90001": "30",
                  "dt_ampm_90001": "AM"
                }

Example — Calendar

application/json


                {
                  "dt_cal_90002": "2024-06-15"
                }

Example — Matrix UniChoice (one row per sub-question)

application/json


                {
                  "u_10010": "20001",
                  "u_10011": "20003",
                  "u_10012": "20002"
                }

Example — Matrix MultiChoice (one row per sub-question)

application/json


                {
                  "m_10010": ["20001", "20002"],
                  "m_10011": ["20003"]
                }

Example — Multi-question page (mixed types)

application/json


                {
                  "u_10001": "50002",
                  "m_10002": ["60001", "60003"],
                  "t_70001": "Additional comments here",
                  "t_80001": "My name",
                  "t_80002": "[email protected]",
                  "r_60001": "1",
                  "r_60002": "2",
                  "s_80010": "50",
                  "s_80011": "30",
                  "s_80012": "20",
                  "dt_day_90001": "15",
                  "dt_month_90001": "6",
                  "dt_year_90001": "2024"
                }

Example Code

cURL — UniChoice answer

Snippet copied successfully.

application/json


                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --header 'Cookie: JSESSIONID={{jsessionid}}' \
                --data '{
                  "u_10001": "50002"
                }'

cURL — MultiChoice answer

Snippet copied successfully.

application/json


                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --header 'Cookie: JSESSIONID={{jsessionid}}' \
                --data '{
                  "m_10002": ["60001", "60003"]
                }'

cURL — Text (open-ended) answer

Snippet copied successfully.

application/json


                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --header 'Cookie: JSESSIONID={{jsessionid}}' \
                --data '{
                  "t_70001": "This is my open-ended response"
                }'

cURL — Multi-question page (mixed types)

Snippet copied successfully.

application/json


                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --header 'Cookie: JSESSIONID={{jsessionid}}' \
                --data '{
                  "u_10001": "50002",
                  "m_10002": ["60001", "60003"],
                  "t_70001": "Additional comments here",
                  "t_80001": "My name",
                  "t_80002": "[email protected]"
                }'

cURL — UniChoice with Other option

Snippet copied successfully.

application/json


                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --header 'Cookie: JSESSIONID={{jsessionid}}' \
                --data '{
                  "u_10001": "50099",
                  "t_50099": "Other — please specify: My custom answer"
                }'

cURL — DateTime answer

Snippet copied successfully.

application/json


                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --header 'Cookie: JSESSIONID={{jsessionid}}' \
                --data '{
                  "dt_day_90001": "15",
                  "dt_month_90001": "6",
                  "dt_year_90001": "2024",
                  "dt_hr_90001": "10",
                  "dt_min_90001": "30",
                  "dt_ampm_90001": "AM"
                }'

cURL — Rank Order answer

Snippet copied successfully.

application/json


                curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page' \
                --header 'Content-Type: application/json' \
                --header 'Accept: application/json' \
                --header 'Cookie: JSESSIONID={{jsessionid}}' \
                --data '{
                  "r_60001": "1",
                  "r_60002": "3",
                  "r_60003": "2"
                }'

Python

Snippet copied successfully.

application/json


                import requests

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

                headers = {
                    "Content-Type": "application/json",
                    "Accept": "application/json"
                }

                #  Use a session to carry the JSESSIONID cookie automatically
                session = requests.Session()

                #  Flat param object — keys come from formParam metadata in the GET /take response
                payload = {
                    "u_10001": "50002",          #  UniChoice: u_<questionId> = <answerId>
                    "t_70001": "Great service!"  #  Text: t_<answerId> = free text
                }

                response = session.post(url, json=payload, headers=headers)
                print(response.text)

PHP - cURL

Snippet copied successfully.

application/json


<?php

$curl = curl_init();
$payload = json_encode([
    "u_10001" => "50002",
    "t_70001"  => "Great service!"
]);

curl_setopt_array($curl, array(
    CURLOPT_URL            => 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/submit-page',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'POST',
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => array(
        'Content-Type: application/json',
        'Accept: application/json',
        'Cookie: JSESSIONID={{jsessionid}}'
    ),
    CURLOPT_COOKIEFILE     => '/tmp/cookie.txt',
    CURLOPT_COOKIEJAR      => '/tmp/cookie.txt',
));

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

Responses

200 OK — Next page loaded (success)

application/json


{
  "response": {
    "status": "success",
    "meta": {
      "isFinalPage": false,
      "progressPercentage": 50
    },
    "navigation": {
      "previousPageUrl": "/a/api/v2/surveys/123456/previous-page",
      "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\":10002,\"type\":\"M\",\"text\":\"Which features do you use?\",\"answers\":[{\"id\":60001,\"text\":\"Dashboard\"},{\"id\":60002,\"text\":\"Reports\"},{\"id\":60003,\"text\":\"Integrations\"}],\"formParam\":{\"paramPrefix\":\"m_\",\"paramIdType\":\"questionId\"}}"
      }
    ]
  },
  "requestID": "9023abcd-f9df-59bf-c900-7r6df398098b"
}

200 OK — Validation errors (same page re-shown)

application/json


{
  "response": {
    "status": "validation_errors",
    "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?\",\"answers\":[...],\"formParam\":{\"paramPrefix\":\"u_\",\"paramIdType\":\"questionId\"}}"
      }
    ],
    "validationErrors": [
      {
        "questionId": 10001,
        "message": "This question is required.",
        "answerErrors": null
      }
    ]
  },
  "requestID": "9023abcd-f9df-59bf-c900-7r6df398098b"
}

200 OK — Survey complete (final page submitted)

application/json


{
  "response": {
    "status": "survey_complete"
  },
  "requestID": "9023abcd-f9df-59bf-c900-7r6df398098b"
}

200 OK — Final page (isFinalPage=true)

application/json


{
  "response": {
    "status": "success",
    "meta": {
      "isFinalPage": true,
      "progressPercentage": 90
    },
    "navigation": {
      "previousPageUrl": "/a/api/v2/surveys/123456/previous-page",
      "nextPageSubmitUrl": "/a/api/v2/surveys/123456/submit-page"
    },
    "themeConfig": {
      "cssUrls": [],
      "jsUrls": []
    },
    "questions": [
      {
        "html": "<div class='qstn-row'>...last page question HTML...</div>",
        "json": "{\"id\":10099,\"type\":\"T\",\"text\":\"Any final comments?\",\"answers\":[{\"id\":99001}],\"formParam\":{\"paramPrefix\":\"t_\",\"paramIdType\":\"answerId\"}}"
      }
    ]
  },
  "requestID": "9023abcd-f9df-59bf-c900-7r6df398098b"
}

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": "array",
          "items": {
            "type": "object",
            "properties": {
              "answerErrors": {
                "type": "string"
              },
              "questionId": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "additionalProperties": false,
            "required": [
              "answerErrors",
              "questionId",
              "message"
            ]
          }
        },
        "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"
  ]
}

400 — Session expired or missing body

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

400 Bad Request Example

application/json


{
  "error": {
    "code": 1002,
    "message": "Session expired. Please load the survey page before submitting."
  },
  "requestID": "9023abcd-f9df-59bf-c900-7r6df398098b"
}

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

formParam Key Construction Guide

How to build submit-page keys from GET /take response

Step 1: Call GET /surveys/{id}/take to get the page.

Step 2: For each question in questions[], parse the json field.

Step 3: Read formParam.paramPrefix and formParam.paramIdType.

Step 4: If paramIdType=questionId → key = paramPrefix + question.id

Step 5: If paramIdType=answerId → key = paramPrefix + answer.id (one key per answer row)

Step 6: For UniChoice, value = the selected answerId string.

Step 7: For MultiChoice, value = array of selected answerId strings.

Step 8: For Text, value = free-text string.

Step 9: If otherParamPrefix is present and Other option is selected, add t_{otherAnswerId}: 'text'.

Quick Reference — All Supported Question Types

U — UniChoice → u_{questionId}: '{answerId}'

M — MultiChoice → m_{questionId}: ['{answerId}', ...]

T — Text/Open-ended → t_{answerId}: 'free text'

CI — Contact Info → t_{answerId}: 'value per field'

R — Rank Order → r_{answerId}: '{rank integer}'

S — Constant Sum → s_{answerId}: '{numeric value}'

DT — DateTime → dt_day_{aId}, dt_month_{aId}, dt_year_{aId} (+ dt_hr_, dt_min_, dt_ampm_ if time enabled)

CAL — Calendar → dt_cal_{answerId}: 'YYYY-MM-DD'

SS — Slider Scale → u_{questionId}: '{answerId}'

SN — Slider Numeric → d_{questionId}: '{numeric value}'

NPS/CSAT/Star Rating → u_{questionId}: '{answerId}'

Matrix UniChoice → u_{rowQuestionId}: '{columnAnswerId}' (one per row)

Matrix MultiChoice → m_{rowQuestionId}: ['{answerId}', ...] (one per row)

File Upload → l_{answerId}: 'file reference'

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

Request Body

Example Code

Responses

formParam Key Construction Guide