Link Search Menu Expand Document

Data export API

Table of contents

  1. Introduction
  2. Authentication
  3. Methods
    1. GET the list of surveys
    2. GET survey responses
    3. GET single survey data
    4. GET visitor info

Introduction

The Data Export API allows you to retrieve survey data from your Survicate account. You can use it to pass all the information collected with Survicate surveys to a database, CRM, or any other custom solution you built.

In particular, data Export API allows you to:

  • retrieve responses collected with your surveys
  • list surveys added to your workspace
  • list questions and possible answers to any particular survey
  • retrieve responses and attributes of each particular respondent

Authentication

curl  -H 'Authorization: Basic {{apiKey}}'

To authenticate your workspace please use your apikey accessible in Data Export API section and add it to your header in format Basic {{apiKey}} provided in Authorization header.


Methods

GET the list of surveys

Survey is a container for all the reponses in our database. As an object, all the properties it has is a name, ID and amount of responses collected.

Attribute Type
id string
name string
responses number

HTTP Request

GET /surveys

cURL

curl -X GET \
  https://data-api.survicate.com/v1/surveys \
  -H 'Authorization: Basic {{apiKey}}'

HTTP Responses

200 OK
Returns a list of all surveys from the workspace.
401 Unauthorised
You are probably missing API key in your call headers.
403 Forbidden
Your subscription is probably insufficient to use Export API.
404 Not found
We didn't get resources you asked for.

Response

[
  {
    "id": "9e4315a8bdcd99c3",
    "name": "My survey",
    "responses": 5143
  }
]

GET survey responses

A survey response is one respondent’s submission of a survey, whether they completed the survey or only partially completed it. API call returns a response as an array of questions and answers along with attributes of respondent, such as their name, email, or job position.

Attribute Type Description
custom_attributes array list of all custom attributes, along with their values
first_seen_date string date and time of first time visitor encountered any of your surveys
first_response_date string date and time of first time visitor responded to a survey
email string respondent’s email
answers array list of questions and responses
survey_point array set of internal question data, such as id and question type
question string content of a question
answer string content of an answer
first_name string respondent’s first name
last_name string respondent’s last name
email string respondent’s email
page_url string URL the survey was submitted on
language string survey translation language (if available)

To get more info about respondent’s attributes please visit our knowledge base

HTTP Request

GET /surveys/{surveyId}/visitors

cURL

curl -X GET \
  https://data-api.survicate.com/v1/surveys/{{surveyId}}/visitors \
  -H 'Authorization: Basic {{apiKey}}'

HTTP Responses

200 OK
Returns a list of all responses to a survey.
401 Unauthorised
You are probably missing API key in your call headers.
403 Forbidden
Your subscription is probably insufficient to use Export API.
404 Not found
We didn't get resources you asked for. Probably the survey was deleted.

Response

[
  {
    "tags": [
      "intercom"
    ],
    "custom_attributes": {
      "consumer_id": "buyers"
    },
    "first_seen_date": "string (date-time)",
    "first_response_date": "string (date-time)",
    "answers": [
      {
        "survey_point": {
          "id": 2542,
          "type": "SurveyQuestion",
          "pretty_type": "Single choice",
          "answer_type": "single"
        },
        "question": "What prevents you from signing up?",
        "content": "I can't find pricing details"
      }
    ],
    "first_name": "John",
    "last_name": "Smith",
    "email": "user@survicate.com",
    "organization": "Survicate",
    "department": "Tech",
    "job_title": "CEO",
    "phone": "726 566 455",
    "website": "string",
    "visitor_hash": "string",
    "country": "Poland",
    "address_one": "View street",
    "address_two": "24/35",
    "city": "Torun",
    "state": "Kuj-pom",
    "zip": "87-100",
    "fax": "+48 56 778 87 78",
    "annual_revenue": "12k USD",
    "employees": "12",
    "industry": "Software Development",
    "identity": "mf4io23n4oin234",
    "comment": "some comment",
    "page_url": "survicate.com",
    "language": "pl",
    "visitor_id": 13,
    "visitor_uuid": "c1a5e21e-91f8-477f-b027-4854a17fd8f9",
    "response_uuid": "2db0724a-5375-489e-9250-d74d7b718ce2"
  }
]

GET call parameters

  • We use pagination in our responses to avoid timeouts. If you get just a part of the results, please use ?page={{pageNumber}} param, where {{pageNumber}} is pagination page you want to collect
  • You can also filter responses using since and until parameters specified in UTC time ISO 8601. E. x. endpoint with parameters: surveys/{{surveyId}}/visitors?since=2019-04-12T10:11:00Z&until=2019-04-15T10:11:00Z will return responses submitted between 2019-04-12 10:11:00 and 2019-04-15 10:11:00

cURL

curl -X GET \
  'https://data-api.survicate.com/v1/surveys/{{surveyId}}/visitors?page=1' \
  -H 'Authorization: Basic {{apiKey}}'

GET single survey data

This method returns list of questions and possible answers, along with their IDs. It can be used in JavaScrips interactions with your surveys, such as setting up EventListeners and setting up custom functions after a response.

Attribute Type Description
name string name of a survey
points array list of questions
answer_type string type of answer - can be text, multiple choice, matrix etc.
answers array list of answers that user can choose from - each answer has it’s id and content

HTTP Request

GET /surveys/{{surveyId}}

cURL

curl -X GET \
  https://data-api.survicate.com/v1/surveys/{{surveyId}} \
  -H 'Authorization: Basic {{apiKey}}'

HTTP Responses

200 OK
Returns a list of questions and possible answers.
401 Unauthorised
You are probably missing API key in your call headers.
403 Forbidden
Your subscription is probably insufficient to use Export API.
404 Not found
We didn't get resources you asked for.

Response

[
  {
    "id": "9e0fb7b8c6cb1f3b",
    "name": "My survey",
    "points": [
      {
        "id": 52334,
        "type": "question",
        "answer_type": "single",
        "content": "How satisfied are you with our service?",
        "answers": [
          {
            "id": 75834,
            "content": "Very satisfied"
          },
          {
            "id": 75835,
            "content": "Somewhat satisfied"
          },
          {
            "id": 75836,
            "content": "Dissatisfied"
          }
        ]

      }
    ]
  }
]

GET visitor info

Visitor is a person responding to a survey. We collect information about visitors throughout surveys, and assign responses to proper visitors. This way, you can easily show all responses of one person along with any attributes collected.

HTTP Request

GET /visitors/{visitorId}

cURL

curl -X GET \
  https://data-api.survicate.com/v1/visitors/{{visitorId}} \
  -H 'Authorization: Basic {{apiKey}}'

HTTP Responses

200 OK
Returns all responses and attributes of a visitor.
401 Unauthorised
You are probably missing API key in your call headers.
403 Forbidden
Your subscription is probably insufficient to use Export API.
404 Not found
We didn't get resources you asked for. Probably the visitor was deleted.

Response

[
  {
    "tags": [
      "intercom"
    ],
    "custom_attributes": {
      "consumer_id": "buyers"
    },
    "first_seen_date": "string (date-time)",
    "reports": [
      {
        "survey_name": "Exit intent survey",
        "platform": "mobile",
        "date": "string (date-time)",
        "answers": [
          {
            "survey_point": {
              "id": 2542,
              "type": "SurveyQuestion",
              "pretty_type": "Single choice",
              "answer_type": "single"
            },
            "question": "What prevents you from signing up?",
            "content": "I can't find pricing details"
          }
        ]
      }
    ],
    "first_name": "John",
    "last_name": "Smith",
    "email": "user@survicate.com",
    "organization": "Survicate",
    "department": "Tech",
    "job_title": "CEO",
    "phone": "726 566 455",
    "website": "string",
    "country": "Poland",
    "address_one": "View street",
    "address_two": "24/35",
    "city": "Torun",
    "state": "Kuj-pom",
    "zip": "87-100",
    "fax": "+48 56 778 87 78",
    "annual_revenue": "12k USD",
    "employees": "12",
    "industry": "Software Development",
    "identity": "mf4io23n4oin234",
    "comment": "some comment",
    "page_url": "survicate.com",
    "id": 1928271,
    "uuid": "56c532c0-d26c-4c89-81f6-9d499c0250b2"
  }
]

👋 If you bump into any problems or need more support, just start a conversation using Intercom in the bottom-right corner and you will be immediately routed to our Customer Support Engineers.