Surveys

List of operations for the resource

Name	URL	Description
List of surveys	`/surveys`	Returns a list of all surveys for the logged-in user. Surveys are sorted by date added in ascending order.
Searching for surveys	`/surveys/search`	Returns a list of surveys matching the search criteria. Surveys are sorted by date added in ascending order.
Survey information	`/surveys/:id`	Detailed information about the survey. Unlike data from the previous operation, this will return information about the domain, theme, and basic information about questions divided into pages.

Description of response parameters

Name/path	Description	Possible values
`id`	Survey ID
`title`	Survey title
`internal_title`	Survey title displayed in the user panel
`url_title`	Survey title used in „friendly links”
`date_created`	Survey creation date
`date_published`	Date of the first publication of the survey – start of collecting results	`null` – if it was not published `$date` – if it was published
`date_modified`	Date of the last modification of the survey	`null` – if it was not modified `$date` – if it was modified
`date_end`	Date of the first end of collecting results	`null` – if it was not ended `$date` – if it was ended
`answers_count`	Number of survey completions
`status`	Survey status	`0` – Survey creation `1` – Collecting results `2` – Analyzing results
`type`	Survey type	`0` – Survey `1` – Test `2` – Website survey
`personal_data`	Personal data in the survey	`0` – are not collected `1` – are collected
`lang_code`	Survey interface language	`pl` – Polish `en` – English
`security_level`	Access to the survey	`1` – Survey available only via direct link. `2` – Survey available only after entering a password. The same password for everyone. `3` – Survey secured with a single-use code (token). As many tokens as there are respondents.
`anonymous`	Identification of respondents	`0` – Enabled – you can link a completion to a respondent. `1` – Disabled – tokens do not allow identification of the respondent. The survey is anonymous.
`password`	Survey access password. Set if `Status == 2`
`many_answers_from_cookie`	Survey completion	`0` – Only once from one device `1` – Any number of completions from one device
`contact_with_author_form`	Displaying a button allowing contact with the survey author	`0` – Disabled `1` – Enabled
`question_numbers`	Displaying question numbers	`0` – Disabled `1` – Enabled
`progress_bar`	Displaying the survey completion progress bar	`0` – Disabled `1` – Enabled
`partial_answers`	Respondents can postpone completion for later	`0` – Disabled `1` – Enabled
`reversible`	Displaying the 'Back' button in surveys with more than one page	`0` – Disabled `1` – Enabled
`answers_limit`	The value of the completion limit after which the study will end
`autostart_date`	Date after which the survey will be automatically activated
`expiration_date`	Date after which the survey will automatically end
`archive`	Information on whether the survey has been archived	`0` – Not archived `1` – Archived
`action_after_answer`	Action after completion	`0` – Displaying a thank you screen `1` – Returning to the beginning of the survey `2` – Redirecting to an external address
`redirection`	The address of the redirect page to which the respondent will be redirected after completing the survey, if `action_after_answer == 2`
`thank_you_text`	Thank you text displayed after completing the survey
`pages.questions.type`	Question type	`0` – Single choice `1` – Matrix single choice `2` – Open-ended `4` – Form `5` – Ranking `6` – Multiple choice `7` – Matrix multiple choice `8` – Slider `9` – Descriptive block `10` – Number `11` – E-mail `12` – Date `13` – Drop-down list `14` – GIODO clause `15` – File upload `16` – NPS `17` – Matrix open-ended `19` – Drag and drop

List of surveys

URL

(GET) https://app.customerhero.com/api/v2/surveys

Optional parameters (POST)

Name	Description
`limit`	Limit on the number of surveys
`offset`	List offset

Example response


[
  {
    "id":69047,
    "title":"Test survey title",
    "url_title":"test-survey-title",
    "date_created":"2011-09-19 13:22:06",
    "date_published":"2011-09-19 13:23:10",
    "date_modified":"2011-09-19 13:23:10",
    "date_end":null,
    "answers_count":0,
    "status":1,
    "type":0,
    "personal_data":0,
    "lang_code":"pl",
    "security_level":0,
    "anonymous":0,
    "password":"",
    "public_results":1,
    "many_answers_from_cookie":1,
    "email_notification":0,
    "comments":1,
    "social_media":1,
    "contact_with_author_form":1,
    "question_numbers":1,
    "progress_bar":0,
    "partial_answers":0,
    "reversible":0,
    "answers_limit":0,
    "expiration_date":null,
    "search_engines":1,
    "action_after_answer":0,
    "redirection":null,
    "thank_you_text":"Thank you for completing the survey"
  },
  {
	...
  }
]

Returned errors

None

Searching for surveys

URL

(GET) https://app.customerhero.com/api/v2/surveys/search

Optional parameters (POST)

Name	Description
`title`	Survey title
`date_created`	Survey creation date. The date must be passed in `YYYY-MM-DD` format (e.g., 2011-11-20). After passing the parameter, all surveys created on that day will be returned.
`date_published`	Date of the first publication of the survey. The date must be passed in `YYYY-MM-DD` format (e.g., 2011-11-20). After passing the parameter, all surveys published on that day will be returned.
`date_end`	Date of the first end of collecting results. The date must be passed in `YYYY-MM-DD` format (e.g., 2011-11-20). After passing the parameter, all surveys ended on that day will be returned.
`status`	Survey status. Allowed values are: `0`, `1`, and `2`
`type`	Survey type. Allowed values are: `0` – survey, `1` – test, and `2` – widget
`security_level`	Survey security level. Allowed values are: `0`, `1`, `2`, and `3`
`limit`	Limit on the number of surveys
`offset`	List offset

Example response

[
  {
    "id":69047,
    "title":"Test survey title",
    "internal_title":"[Project] Test survey title",
    "url_title":"test-survey-title",
    "date_created":"2011-09-19 13:22:06",
    "date_published":"2011-09-19 13:23:10",
    "date_modified":"2011-09-19 13:23:10",
    "date_end":null,
    "answers_count":0,
    "status":1,
    "type":0,
    "personal_data":0,
    "lang_code":"pl",
    "security_level":0,
    "anonymous":0,
    "password":"",
    "public_results":1,
    "many_answers_from_cookie":1,
    "email_notification":0,
    "comments":1,
    "social_media":1,
    "contact_with_author_form":1,
    "question_numbers":1,
    "progress_bar":0,
    "partial_answers":0,
    "reversible":0,
    "answers_limit":0,
    "expiration_date":null,
    "search_engines":1,
    "action_after_answer":0,
    "redirection":null,
    "thank_you_text":"Thank you for completing the survey"
  },
  {
	...
  }
]

Returned errors

400 Bad request – Invalid date format, invalid status, or invalid security level
500 Internal Server Error – Internal server error.

Survey information

URL

(GET) https://app.customerhero.com/api/v2/surveys/:id

Parameters

none

Example response

{
   "id":69047,
   "title":"Test survey title",
   "url_title":"test-survey-title",
   "internal_title":"[Project] Test survey title",
   "date_created":"2011-09-19 13:22:06",
   "date_published":"2011-09-19 13:23:10",
   "date_modified":"2011-09-19 13:23:10",
   "date_end":null,
   "answers_count":0,
   "status":1,
   "type":0,
   "personal_data":0,
   "lang_code":"pl",
   "security_level":0,
   "anonymous":0,
   "password":"",
   "public_results":1,
   "many_answers_from_cookie":1,
   "email_notification":0,
   "comments":1,
   "social_media":1,
   "contact_with_author_form":1,
   "question_numbers":1,
   "progress_bar":0,
   "partial_answers":0,
   "reversible":0,
   "answers_limit":0,
   "expiration_date":null,
   "search_engines":1,
   "action_after_answer":0,
   "redirection":null,
   "thank_you_text":"Thank you for completing the survey",
   "domain":{
      "type":"subdomain",
      "main":false,
      "address":"subdomain.customerhero.com"
   },
   "pages":[
      {
         "id":261181,
         "number":1,
         "questions":[
            {
               "id":804039,
               "type":9,
               "order":1,
               "number":0,
               "text":"Descriptive block",
               "desc":"Welcome.",
               "date_created":"2011-05-06 00:39:14"
               "internalName": ""

            },
            {
               "..."
            }
         ]
      },
      {
         "id":261182,
         "number":2,
         "questions":[
            {
               "id":804041,
               "type":0,
               "order":1,
               "number":1,
               "text":"How did you hear about our restaurant?",
               "desc":"",
               "date_created":"2011-06-27 16:29:50"
               "internalName": ""
            },
            {
               "..."
            }
         ]
      }
   ],
"theme": {
        "id": 252445,
        "title": "Theme name",
        "font": {
            "size": "medium",
            "style": "poppins"
        },
        "logo": {
            "url": "https://files.customerhero.com/user_files/user_logo/424242/image_1765414061.png",
            "size": 38,
            "position": "left",
            "alt": "Logo"
        },
        "backgroundImage": null,
        "colors": {
            "questionText": "#e5e7eb",
            "background": "#121212",
            "controlsBorderAndBackground": "#cbb090",
            "buttonTextColor": "#ffffff",
            "buttonBackgroundColor": "#cbb090"
        },
        "customCss": ""
    },
    "folder": "My projects"
}

Returned errors

404 Not Found – The resource was not found or does not exist.