Questionnaires¶

Note

This API is part of an upcoming larger change to our API. The API documentation already reflects the future version. Until the change, please keep using the endpoints at /questions/. The new version is expected to be released for hosted pretix early December and for self-hosted pretix with version 2027.1. You can find more information on our blog.

Questionnaires are attached to one or more products, and a product can have multiple questionnaires. They consist of questionnaire rows, each of which can be one of the following:

Reference to system field

To reference a system field, use one of the identifier strings from the table below in the row’s datafield attribute. Currently, system fields are only defined on order positions, not on orders.

Container	Identifier	Label
Order position	“@attendee_name_parts”	Attendee name
Order position	“@attendee_email”	Attendee email
Order position	“@company”	Company
Order position	“@street”	Street
Order position	“@zipcode”	ZIP code
Order position	“@city”	City
Order position	“@state”	State
Order position	“@country”	Country

Reference to user-defined data field

To reference a user-defined data field, use its internal reference (identifier) in the row’s datafield attribute.

Static explanation text / subheading

To add a static text block, set the row’s datafield attribute to null. In this case, the text from the label attribute is displayed as a subheading, and the help_text attribute as a normal paragraph.

Resource description¶

Field	Type	Description
id	integer	Internal ID of the questionnaire
type	string	The type of questionnaire. Valid options: `order_purchase` — Order-wide, before purchase `position_purchase` — Per product, before purchase `position_attendee` — Per product, via attendee link `position_checkin` — Per product, at check-in `position_hidden` — Per product, hidden
internal_name	string	Internal label for the questionnaire.
items	list of integers	List of item IDs this questionnaire is assigned to. Only supported on per-product questionnaires.
position	integer	An integer, used for sorting
all_sales_channels	boolean	If `true` (default), the questions from this questionnaire are asked on all sales channels.
limit_sales_channels	list of strings	List of sales channel identifiers the questions are asked on if `all_sales_channels` is `false`.
rows	list of objects	List of all questionnaire rows.
├ datafield	string	Reference to a data field (see above)
├ required	boolean	If `true`, the question needs to be filled out.
├ label	multi-lingual string	The field label shown to the customer. In case of a static text block, the subheading.
├ help_text	multi-lingual string	The help text shown to the customer.
├ dependency_datafield	string	`datafield` reference of a different row in the same questionnaire. The current question will only be shown if the question given in this attribute is set to one of the values given in `dependency_values`.
├ dependency_values	list of strings	If `dependency_datafield` is set to reference a boolean data field, this should be `["True"]` or `["False"]`. Otherwise, it should be a list of `identifier` values of question options.
├ rendered_help_text	string	Read-only. Markdown contents from help_text rendered to HTML

Endpoints¶

GET /api/v1/organizers/(organizer)/events/(event)/questionnaires/¶

Returns a list of all questionnaires within a given event.

Example request:

GET /api/v1/organizers/bigevents/events/sampleconf/questionnaires/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 1,
      "type": "position_purchase",
      "internal_name": "Attendee data",
      "items": [1, 2],
      "position": 0,
      "all_sales_channels": true,
      "limit_sales_channels": [],
      "rows": [
        {
          "datafield": "@attendee_name_parts",
          "required": false,
          "label": {"en": "Attendee name"},
          "help_text": {},
          "dependency_datafield": null,
          "dependency_values": [],
          "rendered_help_text": ""
        },
        {
          "datafield": "@attendee_email",
          "required": false,
          "label": {"en": "Attendee email"},
          "help_text": {"en": "*We'll send you our program guide a few days before the event.*"},
          "dependency_datafield": null,
          "dependency_values": [],
          "rendered_help_text": "<em>We'll send you our program guide a few days before the event.</em>"
        }
      ]
    },
    {
      "id": 2,
      "type": "order_purchase",
      "internal_name": "Per-order questions",
      "items": [],
      "position": 0,
      "all_sales_channels": true,
      "limit_sales_channels": [],
      "rows": [
        {
          "datafield": "87Y8DCS9",
          "required": false,
          "label": {"en": "How did you find us?"},
          "help_text": {},
          "dependency_datafield": null,
          "dependency_values": [],
          "rendered_help_text": ""
        }
      ]
    }
  ]
}

Query Parameters:

page (integer) – The page number in case of a multi-page result set, default is 1
ordering (string) – Manually set the ordering of results. Valid fields to be used are id and position. Default: position
type (string) – Only return questionnaires with the given type
items (string) – Only return questionnaires associated with the given item (internal item ID)
sales_channel (boolean) – Only return questionnaires visible on the given sales channel (sales channel identifier string)

Parameters:

organizer – The slug field of the organizer to fetch
event – The slug field of the event to fetch

Status Codes:

200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.

GET /api/v1/organizers/(organizer)/events/(event)/questionnaires/(id)/¶

Returns information on one questionnaire, identified by its ID.

Example request:

GET /api/v1/organizers/bigevents/events/sampleconf/questionnaires/2/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 2,
  "type": "order_purchase",
  "internal_name": "Per-order questions",
  "items": [],
  "position": 0,
  "all_sales_channels": true,
  "limit_sales_channels": [],
  "rows": [
    {
      "datafield": "87Y8DCS9",
      "required": false,
      "label": {"en": "How did you find us?"},
      "help_text": {},
      "dependency_datafield": null,
      "dependency_values": [],
      "rendered_help_text": ""
    }
  ]
}

Parameters:

organizer – The slug field of the organizer to fetch
event – The slug field of the event to fetch
id – The id field of the questionnaire to fetch

Status Codes:

200 OK – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to view this resource.

POST /api/v1/organizers/(organizer)/events/(event)/questionnaires/¶

Create a new questionnaire

Example request:

POST /api/v1/organizers/bigevents/events/sampleconf/questionnaires/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json

{
  "type": "order_purchase",
  "internal_name": "Per-order questions",
  "position": 0,
  "all_sales_channels": true,
  "rows": [
    {
      "datafield": "87Y8DCS9",
      "required": false,
      "label": {"en": "How did you find us?"}
    }
  ]
}

Example response:

HTTP/1.1 201 Created
Vary: Accept
Content-Type: application/json

{
  "id": 2,
  "type": "order_purchase",
  "internal_name": "Per-order questions",
  "items": [],
  "position": 0,
  "all_sales_channels": true,
  "limit_sales_channels": [],
  "rows": [
    {
      "datafield": "87Y8DCS9",
      "required": false,
      "label": {"en": "How did you find us?"},
      "help_text": {},
      "dependency_datafield": null,
      "dependency_values": [],
      "rendered_help_text": ""
    }
  ]
}

Parameters:

organizer – The slug field of the organizer of the event to create a questionnaire for
event – The slug field of the event to create a questionnaire for

Status Codes:

201 Created – no error
400 Bad Request – The questionnaire could not be created due to invalid submitted data.
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to create this resource.

PATCH /api/v1/organizers/(organizer)/events/(event)/questionnaires/(id)/¶

Update a questionnaire. You can also use PUT instead of PATCH. With PUT, you have to provide all fields of the resource, other fields will be reset to default. With PATCH, you only need to provide the fields that you want to change.

You can only change all rows en bloc, or keep all of them unchanged in case of a PATCH. If you change rows, you need to specify all fields of the resource.

Example request:

PATCH /api/v1/organizers/bigevents/events/sampleconf/questionnaires/2/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript
Content-Type: application/json

{
  "internal_name": "Questions asked per order"
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "id": 2,
  "type": "order_purchase",
  "internal_name": "Questions asked per order",
  "items": [],
  "position": 0,
  "all_sales_channels": true,
  "limit_sales_channels": [],
  "rows": [
    {
      "datafield": "87Y8DCS9",
      "required": false,
      "label": {"en": "How did you find us?"},
      "help_text": {},
      "dependency_datafield": null,
      "dependency_values": [],
      "rendered_help_text": ""
    }
  ]
}

Parameters:

organizer – The slug field of the organizer of the questionnaire to modify
event – The slug field of the event of the questionnaire to modify
id – The id field of the questionnaire to modify

Status Codes:

200 OK – no error
400 Bad Request – The questionnaire could not be modified due to invalid submitted data
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to change this resource.

DELETE /api/v1/organizers/(organizer)/events/(event)/questionnaires/(id)/¶

Delete a questionnaire.

Example request:

DELETE /api/v1/organizers/bigevents/events/sampleconf/questionnaires/1/ HTTP/1.1
Host: pretix.eu
Accept: application/json, text/javascript

Example response:

HTTP/1.1 204 No Content
Vary: Accept

Parameters:

organizer – The slug field of the organizer of the questionnaire to modify
event – The slug field of the event of the questionnaire to modify
id – The id field of the questionnaire to delete

Status Codes:

204 No Content – no error
401 Unauthorized – Authentication failure
403 Forbidden – The requested organizer/event does not exist or you have no permission to delete this resource.