SurveyGizmo OEM API (v1)

Download OpenAPI specification:Download

Overview

Welcome to SurveyGizmo's Original Equipment Manufacturer (OEM) API documentation. SurveyGizmo's OEM API enables developers to programmatically interact with SurveyGizmo's application, enabling you to create and style surveys and collect and report on survey data. Leverage SurveyGizmo's robust and powerful features in your own application!

Check out our Getting Started Guide to see how quickly and easily you can start building surveys!

Getting Started Guide

How to build a survey via the API

Prerequisites

These instructions describe how to create your first survey using cURL calls.

Before you can start using the API, you need to do the following:

  1. Open a SurveyGizmo OEM account. To open an OEM API account contact our partnerships team at partnerships@surveygizmo.com.
  2. Log into Developer's Resource Center at app.surveygizmo.com and obtain your test API key.
  3. Make sure you have cURL or an HTTP client like Postman or Insomnia installed on your machine.

Build your API call

Your API call must have the following components:

  1. A Host - The host for API requests is https://oem.surveygizmo.com/v1/
  2. Authentication - Include an x-api-key header using either your test or live API key.
  3. A Request - When submitting data to a resource via POST,PUT or PATCH, you must submit your payload in JSON.

Build a survey via the API

To build a simple survey via the API start by creating a survey:

  1. Copy the cURL example below.
  2. Paste the cURL call into a text editor.
  3. Copy your API key and paste it in x-api-key header.
  4. In the data section, customize the title if you wish to customize.
  5. Copy the code, paste, and run it in your terminal (or HTTP client).

Note: There are additional options available for surveys. Learn more in the Surveys Resource Documentation..

curl --request POST \
  --url 'https://oem.surveygizmo.com/v1/surveys/' \
  --header 'content-type: application/json' \
  --header 'x-api-key: test_1234567890_0123456789abcd.12345678' \
  --data '{"title,": "Customer Survey"}'

You've created your first survey via the API!

Note in the response that the survey was created with two pages. The first page is a blank page. The second is a Thank You page.

Now, find the share_link in your response. Copy and paste into your browser's address bar.

You'll see that, despite the fact that your survey was created with two pages, you are taken to the thank you page. This is because survey pages will not display if they have no content.

Note too that the Thank You Page has neither a Next nor a Back button. Data is collected in SurveyGizmo surveys when the Next button at the bottom of the page is clicked. Because Thank You Pages are terminal pages, used by the SurveyGizmo system to mark the response as complete, they are unable to collect data.

Our next step is to add a question to the first page of your survey!

Build a question via the API

To build a simple textbox question:

  1. Copy the cURL example below.
  2. Paste the cURL call into a text editor.
  3. Copy your API key and paste it in x-api-key header.
  4. Go back to the response from your page create call and copy and paste the ID after pages/ in the URL.
  5. In the data section, customize the question title if you wish.
  6. Copy the code, paste, and run it in your terminal (or HTTP client).

Note: There are additional quetion types and question options available. Learn more in the Questions Resource Documentation..

curl --request POST \
  --url https://app.bri.dev.sg53.net/services/latest/surveys/1244323/pages/1/questions \
  --header 'content-type: application/json' \
  --header 'x-api-key: test_1234567890_0123456789abcd.12345678' \
  --data '{"type": "textbox","title": "What is your name?"}'

You've created your first question via the API! This also completes the core of survey building via the API.

If you return to your share_link from your survey create response you'll see your textbox question. Now, you're ready for next steps!

Next Steps

  1. Create additional types of questions.
  2. Add pages to your survey.
  3. Update your survey and page settings.
  4. Get the responses to your survey.
  5. Style your survey's theme.
  6. Translate your survey.

Developer Resource Center

Access the Developer's Resource Center at app.surveygizmo.com.

Don't have an account? Contact our partnerships team at partnerships@surveygizmo.com

Your resource center will include usage info, API keys and logs, billing info.

Usage Stats and Logs

Within the Developer's Resource Center under Account > Summary > Account Overview you'll have a usage chart that displays usage for both your test and live keys. Calls will take up to 30 minutes to display on the usage chart.

API Usage Stats

On the Logs tab you will have a log of calls.

API Logs

API Key Management

Your API account will include a test and live key. Click the View link to access your keys. You will be prompted to enter your password; once you have done so your key will display. If, for security reasons, you need to regenerate a key you can do so by clicking the Regenerate link next to the key. Upon regeneratio of a key, old keys will no longer work.

API Key Management

Data created using test keys

Data created via test keys will be deleted after 24 hours. Survey subresources (e.g. pages, questions, translations, responses etc.) will be deleted along with the survey.

Whitelist IPs

Within the Developer's Resource Center you can limit IP addresses from which API calls will be allowed. To do so go to Account > Summary > Account Overview and scroll to the Whitelisted IP Addresses. Click Edit to add/remove IP addresses.

Whitelist IP Addresses

You can whitelist IP addresses or network blocks for a set of IP addresses. If whitelisting an individual IP address, we support IPv4 and IPv6. If you're entering a network block, we support CIDR notation. Refer to this CIDR notation Wikipedia article for more details about how to use CIDR notation.

Type Examples
IPv4 104.192.143.1
IPv6

2401:1d80:1010::150

CIDR block 104.192.143.0/28
2401:1d80:1010::/64
2401:1d80:1010::150/128

Billing

On the Billing tab of the Developer's Resource Center you can update your billing and payment info. Invoices and receipts are also available on the Billing tab. Billing issues? Contact partnerships@surveygizmo.com.

Billing

Technical Support

Our support team is available to assist you with account-level questions, as well as, troubleshooting issues with the success/failure of your API calls. Assistance with your implementation of the API is beyond the scope of our support team.

To contact support, log into the Developer's Resource Center and click Need Help in the upper-right corner of the screen. At the bottom of the panel click No, show additional support options. This will display your options for contacting support. You can also contact the partnerships team for support at partnerships@surveygizmo.com.

We also encourage you to work with other developers in our Community to address implementation and best practice questions.

Authentication

To authenticate your calls include your test or live key as an x-api-key header in API requests. You can manage your API keys in the Developer's Resource Center.

Response Codes and Errors

All API responses share a common wrapper that includes information about the success or failure of the request.

Field Description Data Type
success Success true/false boolean
code HTTP response code integer
message Response message string
errors Array of errors, may be empty array[objects]
{
  "success": true,
  "code": "200",
  "type": "surveys",
  "message": "success",
  "errors":{
    "field": "",
    "message": ""
  }
} 

SurveyGizmo uses conventional HTTP response codes to indicate the success or failure of an API request. The following error codes are implemented:

Code Description
200 OK
201 Created
400 Bad Request
403 Forbidden
404 Not Found
405 Method Not Allowed
413 Request Entity Too Large
422 Unprocessable Entity
429 Too Many Requests
500 Internal Server Error
501 Not Implemented

Pagination

All API resources (with the exception of the data resources) have support for bulk fetches via "list" API method. These list API methods accept two query paramenters page and per_page and share a common pagination structure.

Paging Query Parameters Default Description
page 1 Page to return
per_page 25 (max 100) Number of results to return per page

Pagination Response Schema

Field Description Data Type
page Current page number integer
per_page Number of results per page integer
page_count Number of total pages integer
total_count Total number or results integer
links Collection of objects including a link for first, last, next, and previous when applicable array
"pagination": {
    "page": 3,
    "per_page": 25,
    "page_count": 10,
    "total_count": 250,
    "links": {
        "first": "/surveys?page=1&per_page=25",
        "previous": "/surveys?page=2&per_page=25",
        "next": "/surveys?page=4&per_page=25",
        "last": "/surveys?page=10&per_page=25"
    }

Limits

In order to ensure consistent service, all API calls have a request limits. The request limit is enforced per API key.

  • Test Calls - 2 requests per second
  • Live Calls - 25 requests per second

Filters

Filter/Segment Customer Data

Use the owner_id field on the survey, themes, and contacts resources to manage and segment customers' data. Using the x-owner-id header you can filter all get list calls by a particular customer's owner ID.

Because pages, questions, translations, responses, and data are a subresources of surveys the owner_id field on the survey object will be automatically applied to these resources.

Responses Resource Filters

In addition to the x-owner-id header for filtering API calls to keep your customers' data segmented, the responses resource supports a filter query parameter that accepts a JSON string.

How to build a filter

Specify a field, operator, and value for each condition. Conditions can be joined by AND/OR. Use an array of option SKUs to specify answer options in the value field.

Construct simple conditions like so:

"filter": {
    "condition": "AND",
    "rules": [
        {
            "field": "question_2",
            "operator": "equal",
            "value":[
                10011
            ]
        },
        {
            "field": "url_region",
            "operator": "equal",
            "value": "midwest"
        }
    ]
}

Construct complex conditions like so:

"filter": {
  "condition": "AND",
  "rules": [
    {
      "field": "date_submitted",
      "operator": "date_after",
      "value": "2018-01-01T00:00:00Z"
    },
    {
      "condition": "OR",
      "rules": [
        {
          "field": "question_2",
          "operator": "equal",
          "value": [
                10002
            ]
        },
        {
          "field": "url_region",
          "operator": "equal",
          "value": "midwest"
        }
      ]
    }
  ]
}

Available Fields

  • date_submitted - Date and time response was submitted in UTC (Format: 2018-01-01T00:00:00Z)
  • question_{id} - The question you wish to use in the logic condition. Specify using the id like so: question_2 (remove curly braces)
  • is_test_data - Test data flag
  • contact_id - Contact ID from contacts resource
  • response_status - complete, partial, disqualified, deleted
  • url_{key} - URL variable (remove curly braces)

Available Operators

  • equal
  • not_equal
  • in
  • not_in
  • is_answered
  • is_not_answered
  • less
  • less_or_equal
  • greater
  • greater_or_equal
  • date_before
  • date_after

Survey Logic

Logic conditions – conditions that determine when an element shows – can be set for both questions and pages. Use an array of option SKUs to specify answer options in the value field.

How to build logic conditions

Specify a field, operator, and value for each condition. Conditions can be joined by AND/OR.

Logic conditions come in two flavors:

  1. Unit rules - one or multiple conditions joined by the same AND/OR operator
  2. Condition rules - multiple conditions joined by multiple AND/OR operators

Construct unit rules like so (see a complete, postable example below):

logic_rules: {
    "condition": "AND",
    "rules": [
        {
            "field": "question_2",
            "operator": "in",
            "value": [
                10001
            ]
        },
        {
            "field": "url_region",
            "operator": "equal",
            "value": "midwest"
        }
    ]
}

Construct condition rules like so (See a complete, postable example below):

logic_rules: {
  "condition": "AND",
  "rules": [
    {
      "field": "date_submitted",
      "operator": "date_after",
      "value": "2018-01-01T00:00:00Z"
    },
    {
      "condition": "OR",
      "rules": [
        {
          "field": "question_2",
          "operator": "in",
          "value": [
                10001
            ]
         },
        {
          "field": "url_region",
          "operator": "equal",
          "value": "midwest"
        }
      ]
    }
  ]
}

Available Fields

  • question_{id} - The question you wish to use in your logic condition. id is assigned on question creation and returned in the POST response. Specify without the curly braces like so: question_2
  • url_{key} - URL variable (remove curly braces)
  • contact_id - Contact ID from contacts resource
  • email_address - Email address from contacts resource
  • first_name - First name from contacts resource
  • last_name - Last name from contacts resource
  • organization - Organization from contacts resource
  • division - Division from contacts resource
  • department - Department from contacts resource
  • team - Team from contacts resource
  • group - Group from contacts resource
  • role - Role from contacts resource
  • home_phone - Home phone from contacts resource
  • fax_phone - Fax phone from contacts resource
  • business_phone - Business phone from contacts resource
  • mailing_address - Mailing address from contacts resource
  • mailing_address_2 - Mailing address field 2 from contacts resource
  • mailing_address_city - City from contacts resource
  • mailing_address_state - State from contacts resource
  • mailing_address_country - Country from contacts resource
  • mailing_address_postal - Postal code from contacts resource
  • title - Title from contacts resource
  • url - URL from contacts resource
  • custom fields - Use your custom field key as field
  • time_on_survey - Time spent on survey
  • current_date - Current date pulled from respondent's system
  • is_mobile - Use to conditionally show/hide something if respondents are on a mobile device.
  • ip_address - Respondent's IP address
  • country - Respondent's country (determined by IP)
  • region - Respondent's region (determined by IP)
  • postal_code - Respondent's postal_code (determined by IP)
  • city - Respondent's city (determined by IP)

Available Operators

  • equal
  • not_equal
  • in
  • not_in
  • is_answered
  • is_not_answered
  • less
  • less_or_equal
  • greater
  • greater_or_equal
  • date_before_or_equal
  • date_after_or_equal
  • matches_regex_pattern
  • does_not_match_regex_pattern
  • is_true
  • is_false
  • contains
  • is_always_true

Complete, postable example of a unit rule

The below example will create a two-question survey where the second question has logic rules such that it only shows if the first question's (question_2) answer is Dogs AND Cats.

{
  "title": "Customer Survey",
  "internal_title": "Q2 Customer Survey",
  "status": "open",
  "pages": [
    {
      "questions": [
        {
          "type": "checkboxes",
          "title": "Which pets do you have?",
          "options": [
            {
              "title": "Dog/s"
            }, 
            {
              "title": "Cat/s"
            },
            {
              "title": "Bird/s"
            },
            {
              "title": "Reptile/s"
            }
          ]
        },
        {
          "type": "radiobuttons",
          "title": "Which do you prefer, cats or dogs?",
          "logic_rules": {
              "type": "rulesunit",
              "condition": "AND",
              "rules": [
                  {
                      "field": "question_2",
                      "operator": "in",
                      "value": [
                          10001
                      ]
                  },
                {
                      "field": "question_2",
                      "operator": "in",
                      "value": [
                          10002
                      ]
                  }
              ]
          },
          "options": [
            {
              "title": "Dogs"
            }, 
            {
              "title": "Cats"
            }
          ]
        }
      ]
    }
  ]
}

Complete, postable example of a condition rule

The below example will create a three-question survey where the third question has logic rules such that it only shows if the first question's (question_2) answer is "No, but I plan to get one" OR the second questions answer is either "Cats" OR "Dogs".

{
  "title": "Customer Survey",
  "internal_title": "Q2 Customer Survey",
  "status": "open",
  "pages": [
    {
      "questions": [
        {
          "type": "radiobuttons",
          "title": "Do you have pets?",
          "options": [
            {
              "title": "Yes"
            }, 
            {
              "title": "No"
            },
            {
              "title": "No, but I plan to get one"
            }
          ]
        },
        {
          "type": "checkboxes",
          "title": "Which pets do you have?",
          "options": [
            {
              "title": "Dog/s"
            }, 
            {
              "title": "Cat/s"
            },
            {
              "title": "Bird/s"
            },
            {
              "title": "Reptile/s"
            }
          ]
        },
        {
          "type": "radiobuttons",
          "title": "Are you interested in pet insurance?",
          "logic_rules": {
              "type": "rulescondition",
              "condition": "OR",
              "rules": [
                  {
                      "field": "question_2",
                      "operator": "in",
                      "value": [
                          10001
                      ]
                  },
                  {
                      "condition": "OR",
                      "rules": [
                          {
                              "field": "question_3",
                              "operator": "in",
                              "value": [
                                  10002
                              ]
                          },
                          {
                              "field": "question_3",
                              "operator": "in",
                              "value": [
                                  10003
                              ]
                          }
                      ]
                  }
              ]
          },
          "options": [
            {
              "title": "Yes"
            }, 
            {
              "title": "No"
            }
          ]
        }
      ]
    }
  ]
}

API Resources

API Endpoint: https://oem.surveygizmo.com/v1/

Using SurveyGizmo's OEM API you have access to the following resources:

  1. Surveys: List, Create, Get, Replace, Update, and Delete
  2. Pages: List, Create, Get, Replace, Update, and Delete
  3. Questions: List , Create, Get, Replace, Update, and Delete
  4. Themes: List, Create, Get, Replace, Update, and Delete
  5. Translations: List, Create, Get, Replace, Update, and Delete
  6. Contacts: List, Create, Get, Replace, Update, and Delete (as well as list, add, get, remove from surveys)
  7. Responses: List, Create, Get, Replace, Update, and Delete
  8. Aggregate Data: List response data and Get aggregate data per question

A Note About Polymorphic Resources

Many of these resources accept and return multiple models.

For example, the Questions resource accepts and returns a model per question type (there are 50 including actions). When using documentation be sure to utilize the dropdown menu to view your desired model.

Question Type Models

Other polymorphic resources:

  • Surveys - Surveys have a basic and a full model. Use the detail_level query parameter to determine which model is returned on the get method. For post, patch, and put if the pages object is present the full model will be used.
  • Subquestions - Several question types have subquestions (Contact Forms, Custom Groups, and Custom Tables). As such, there are various models used to post and return data to these subquestions.
  • Responses - Response data assumes a format similar to the question models.
  • Data - There are several models for aggregate data for questions.