API

The API is organized around REST and uses standard HTTP response codes to identify errors. All API responses will be in JSON format, including errors.

The API works with any software that has a HTTP library, such as cURL. It can also be used directly from any browser.

Clients can send petitions through HTTPS protecting even more the information flow.

API Endpoint

API calls should always be pointed to the following endpoint. From that point onwards they will vary by version and by used resources.

https://api.surveykiwi.com

Auth

Before being able to use the API, first you will have to authenticate with your ACCESS KEYS (API_KEY and API_SECRET) that you can find or generate in “My account” section. If the keys have been created they will appear in your examples but only you will be able to see them.

As a result you will receive an access_token that will allow you to do calls to the API. You can use this token as long as it is valid and has not expired. If any of these things happen you will have to request another one.

These keys are private and unique and should not be shared with anyone and should not be shown in any client-side code.

Returns

Returns an object with the type of token, the token itself and a numeric value that indicates, in seconds, the time that the token can be used.

curl -X POST https://api.surveykiwi.com/oAuth2/token \
    -d grant_type=Client_Credentials \
    -d client_id=API_KEY \
    -d client_secret=API_SECRET
{
    "token_type": "Bearer",
    "expires_in": 900,
    "access_token": "[ACCESS_TOKEN]",
    "refresh_token": "[REFRESH_TOKEN]"
}

Errors

Survey Kiwi uses conventional HTTP response codes to indicate the success or failure of an API request.

In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with Survey Kiwi's servers (these are rare).

Attributes
  • error

    The type of error returned. Can be: invalid_token, method_exception, validation_exception, Unauthorized, not_found, internal_server_error, service_unavailable,

  • error_description

    It’s the description of the error in a friendly format.

HTTP Status Code Summary

200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided or you might be trying to access unauthorized information.
404 - Not Found The requested resource doesn't exist.
405 - Method Not Allowed The method (GET, POST, PUT, DELETE) is not allowed for this petition.
500, 502, 503, 504 - Server Errors Something went wrong with the servers.

Errors

Types
invalid_token The access token provided is expired, revoked, malformed, or invalid for other reasons.
method_exception The method being used is not allowed.
validation_exception This [question/campaign/etc] does not belong to you, unknown parameter, etc.
Unauthorized You are not authorized to perform this action.
not_found Resource not found.
internal_server_error There has been a problem with the server.
service_unavailable Service is currently unavailable.

Pagination

All the resources that return a list of objects can be paginated.

Use two parameters, offset and limit, to offer the possibility of paginating results.

Parameters
  • limit optional, default is 10

    Limit the amount of objects to be returned, between 1 and 100.

  • offset optional, default is 0

    Number that represents the position where results will be returned.

curl -G https://api.surveykiwi.com/v1.0/campaign/list \
    --header "Authorization: Bearer [ACCESS_TOKEN]" \
    -d offset=0 \
    -d limit=2
[
    {
        "id": "55486",
        "project_name": "Employee Satisfaction Survey",
        "url": "satisfaction-employee",
        "state": "active",
        "language": "en-us",
        "show_responses": 0,
        "hidden_fields": 1,
        "participants": 4,
        "questions": [],
        "created_at": "2021-10-06T12:14:23-0300",
        "updated_at": "2021-10-06T12:15:34-0300"
    },{
        "id": "55482",
        "project_name": "Product test",
        "url": "product-test",
        "state": "active",
        "language": "en-us",
        "show_responses": 0,
        "hidden_fields": 1,
        "participants": 10,
        "questions": [],
        "created_at": "2021-10-06T11:52:06-0300",
        "updated_at": "2021-10-06T11:58:07-0300"
    },     
]

Campaign

With this resource you will be able to make requests to obtain a list of your available campaigns and a list of responses of each campaign.

Campaign list

You will be able to request all of your campaigns filtering by different parameters.

Parameters
  • access_token required

    Token obtained in /oAuth2/token.

  • show_questions optional, default is 0

    Define if you want the response to include a list of questions associated with the campaign. 0 or 1.

  • show_options optional, default is 0

    Define if you want the response to include the list of options associated with each question of your campaign. 0 or 1.

  • offset optional, default is 0

    The number of the first response that you want.

  • limit optional, default is 10

    Limit the amount of responses, between 1 and 100.

  • order_by[] optional, default is null

    Rule for order the results. Variable+ASC|DESC separated by comma.

  • where[] optional, default is null

    Rule for filtering results, JSON format. JSON variables are: type, var, operator and val. The type variable accepts as possible results default and it's used to define in what environment it should be searched val. The variable var accepts as possible values most of the object’s variables inside the defined environment by type. The variable operator accepts as possible values operators such as "=", "<", ">", "<=", ">=", "IS", "IS NOT", etc. The variable val accepts as value any data.

Returns

Return a list of objects. Each one contains the information of a campaign, the questions and options.

GET https://api.surveykiwi.com/v1.0/campaign/list
curl -G https://api.surveykiwi.com/v1.0/campaign/list \
    --header "Authorization: Bearer [ACCESS_TOKEN]" \
    -d show_questions=1 \
    -d show_options=1 \
    -d offset=0 \
    -d limit=2 \
    -d order_by[]=created_at,DESC \
    -d where[]='{"type":"default","var":"created_at","operator":"<=","val":"2021-10-22T16:06:36-0300"}'
[
    {
        "id": "55486",
        "project_name": "Employee Satisfaction Survey",
        "url": "satisfaction-employee",
        "state": "active",
        "language": "en-us",
        "show_responses": 0,
        "hidden_fields": 1,
        "participants": 4,
        "questions": [
            {
                "id": "542079",
                "question": "Please select your department",
                "description": null,
                "type": "multiple_picture",
                "picture": null,
                "options": [
                    {
                        "id": "1885043",
                        "option": "Operations",
                        "thumbnail": "https://d3ejpfy8d58pjw.cloudfront.net/campaigns5f1854022ce73_e9ad2ffa416034b6daacf51cf28d77d9.png",
                        "alert": null
                    },{
                        "id": "1885044",
                        "option": "Marketing",
                        "thumbnail": "https://d3ejpfy8d58pjw.cloudfront.net/campaigns5f18540d5584c_8d22454e916e009169c4f3c71ad17719.png",
                        "alert": null
                    },                    
                    {...}
                ]
            },{
                "id": "542080",
                "question": "How long have you worked for the company?",
                "description": null,
                "type": "multiple_choice",
                "picture": null,
                "options": [
                    {
                        "id": "1885051",
                        "option": "Less than 3 months",
                        "thumbnail": null,
                        "alert": null
                    },{
                        "id": "1885052",
                        "option": "Between 3 months and 1 year",
                        "thumbnail": null,
                        "alert": null
                    },                    
                    {...}
                ]
            },            
            {...}
        ]
        "created_at": "2021-10-06T12:14:23-0300",
        "updated_at": "2021-10-06T12:15:34-0300"
    },{
        "id": "55482",
        "project_name": "Product test",
        "url": "product-test",
        "state": "active",
        "language": "en-us",
        "show_responses": 0,
        "hidden_fields": 1,
        "participants": 10,
        "questions": [
            {
                "id": "542026",
                "question": "How much time have you been using the product? ",
                "description": null,
                "type": "multiple_choice",
                "picture": null,
                "options": [
                    {
                        "id": "1884929",
                        "option": "Less than 1 week",
                        "thumbnail": null,
                        "alert": null
                    },{
                        "id": "1884930",
                        "option": "Between 1 week and 1 month",
                        "thumbnail": null,
                        "alert": null
                    },                    
                    {...}
                ]
            },{
                "id": "542027",
                "question": "From the following, select any brands that you have bought or tried in the past. ",
                "description": null,
                "type": "multiple_choice",
                "picture": null,
                "options": [
                    {
                        "id": "1884934",
                        "option": "BRAND 1",
                        "thumbnail": null,
                        "alert": null
                    },{
                        "id": "1884935",
                        "option": "BRAND 2",
                        "thumbnail": null,
                        "alert": null
                    },                    
                    {...}
                ]
            },            
            {...}
        ]
        "created_at": "2021-10-06T11:52:06-0300",
        "updated_at": "2021-10-06T11:58:07-0300"
    },
]

Responses from a campaign

You can request the responses from a particular campaign.

Parameters
  • access_token required

    Token obtained in /oAuth2/token.

  • campaign_url required

    "URL name" unique to each campaign. ex: satisfaction_survey

  • status optional, default is "all"

    Allows active, pending, all. Choose if you want to filter the responses from users that have finished your campaign or not.

  • answers optional, default is "show"

    Allows hide, show. Choose if you want to show the responses from a respondent.

  • offset optional, default is 0

    The number of the first response that you want.

  • limit optional, default is 10

    Limit the amount of responses, between 1 and 100.

  • order_by[] optional, default is null

    Rule for order the results. Variable+ASC|DESC separated by comma.

  • where[] optional, default is null

    Rule for filtering results, JSON format. JSON variables are: type, var, operator and val. The type variable accepts as possible results hiddenfields, participant and default and it's used to define in what environment it should be searched val. The variable var accepts as possible values most of the object’s variables inside the defined environment by type. The variable operator accepts as possible values operators such as "=", "<", ">", "<=", ">=", "IS", "IS NOT", etc. The variable val accepts as value any data.

Returns

Returns a list with objects. Each object contains the information gathered when a user answers a campaign. Data from the respondent, hiddenfields, list of the questions with the selected responses, etc.

GET https://api.surveykiwi.com/v1.0/campaign/answers
curl -G https://api.surveykiwi.com/v1.0/campaign/answers \
    --header "Authorization: Bearer [ACCESS_TOKEN]" \
    -d campaign_url=product-test \
    -d status=active \
    -d offset=0 \
    -d limit=2 \
    -d order_by[]=created_at,DESC \
    -d where[]='{"type":"default","var":"created_at","operator":"<=","val":"2021-10-22T16:06:36-0300"}'
[
    {
        "participant": {
            "id": "1840844",
            "customs": null,
        },
        "hiddenfields": {
            "name": "Sergei",
            "email": "sergei@google.com",
        },
        "questions": [
            {
                "id": "542036",
                "question": "To start with, choose your gender",
                "description": "If you don't want to answer this question you can just click NEXT.",
                "answers": [
                    "https://d3ejpfy8d58pjw.cloudfront.net/campaigns/5f4cfb3f5a555_6e48f2c839ab63c6d7710f9ea4d13bc9.png",
                ]
            },
            {
                "id": "542026",
                "question": "How much time have you been using the product? ",
                "description": null,
                "answers": [
                    "Less than 1 week",
                ]
            },
            {
                "id": "542035",
                "question": "What was your first impression with the product?",
                "description": null,
                "answers": [
                    "Very positive",
                ]
            },
            {
                "id": "542027",
                "question": "From the following, select any brands that you have bought or tried in the past. ",
                "description": null,
                "answers": [
                    "BRAND 2",
                    "BRAND 3",
                    "BRAND 4",
                    "BRAND 5",
                ]
            },
            {
                "id": "542028",
                "question": "When you bought the product, did you analyze any other brands or just our product? ",
                "description": null,
                "answers": [
                    "I analyzed several brands",
                ]
            },
            {
                "id": "542029",
                "question": "How frecuently do you use the product?",
                "description": null,
                "answers": [
                    "More than once a day",
                ]
            },
            {
                "id": "542030",
                "question": "The following questions will be regarding attributes and characteristics of the product.",
                "description": null,
                "answers": [],
            },
            {
                "id": "542031",
                "question": "Which of the following was the most important characteristic for you to decide to acquire the product?",
                "description": "Choose only the MOST important one.",
                "answers": [
                    "Design",
                ]
            },
            {
                "id": "542032",
                "question": "Which is you current <b>general satisfaction</b> level with the product? ",
                "description": null,
                "answers": [
                    "Completely satisfied",
                ]
            },
            {
                "id": "542033",
                "question": "Would you recommend this product to a friend who is looking for a product inside this category?",
                "description": null,
                "answers": [
                    "10",
                ]
            },
            {
                "id": "542034",
                "question": "If you could change something about the product, what would it be?",
                "description": null,
                "answers": [
                    "Perfect product. I will definitely continue using it",
                ]
            },
        ],
        "created_at": "2021-10-06T12:12:32-0300",
        "finished_at": "2021-10-06T12:13:10-0300",
        "duration": 38,
        "score": 0.00,
    },
    {
        "participant": {
            "id": "1840832",
            "customs": null,
        },
        "hiddenfields": {
            "name": "Joe",
            "email": "joe@gmail.com",
        },
        "questions": [
            {
                "id": "542036",
                "question": "To start with, choose your gender",
                "description": "If you don't want to answer this question you can just click NEXT.",
                "answers": [
                    "https://d3ejpfy8d58pjw.cloudfront.net/campaigns/5f4cfb3f5a555_6e48f2c839ab63c6d7710f9ea4d13bc9.png",
                ]
            },
            {
                "id": "542026",
                "question": "How much time have you been using the product? ",
                "description": null,
                "answers": [
                    "Between 6 months and 1 year",
                ]
            },
            {
                "id": "542035",
                "question": "What was your first impression with the product?",
                "description": null,
                "answers": [
                    "Very negative",
                ]
            },
            {
                "id": "542027",
                "question": "From the following, select any brands that you have bought or tried in the past. ",
                "description": null,
                "answers": [
                    "BRAND 4",
                    "BRAND 5",
                ]
            },
            {
                "id": "542028",
                "question": "When you bought the product, did you analyze any other brands or just our product? ",
                "description": null,
                "answers": [
                    "I analyzed one or two brands at most",
                ]
            },
            {
                "id": "542029",
                "question": "How frecuently do you use the product?",
                "description": null,
                "answers": [
                    "Less than once a week",
                ]
            },
            {
                "id": "542030",
                "question": "The following questions will be regarding attributes and characteristics of the product.",
                "description": null,
                "answers": [],
            },
            {
                "id": "542031",
                "question": "Which of the following was the most important characteristic for you to decide to acquire the product?",
                "description": "Choose only the MOST important one.",
                "answers": [
                    "Size",
                ]
            },
            {
                "id": "542032",
                "question": "Which is you current <b>general satisfaction</b> level with the product? ",
                "description": null,
                "answers": [
                    "Dissatisfied",
                ]
            },
            {
                "id": "542033",
                "question": "Would you recommend this product to a friend who is looking for a product inside this category?",
                "description": null,
                "answers": [
                    "2",
                ]
            },
            {
                "id": "542034",
                "question": "If you could change something about the product, what would it be?",
                "description": null,
                "answers": [
                    "Terrible quality of the product",
                ]
            },
        ],
        "created_at": "2021-10-06T12:01:39-0300",
        "finished_at": "2021-10-06T12:02:13-0300",
        "duration": 34,
        "score": 0.00,
    },
]

Question

With this resource you will be able to obtain a unique object with the information of a specific question.

Details of a question

You will get the details of a specific question by sending its ID as a parameter.

Parameters
  • access_token required

    Token obtained in /oAuth2/token.

  • id required

    Unique ID of the question

Returns

Returns an object with all the information available from a particular question and its options.

GET https://api.surveykiwi.com/v1.0/question
curl -G https://api.surveykiwi.com/v1.0/question \
    --header "Authorization: Bearer [ACCESS_TOKEN]" \
    -d id=542026
{
        "id": "542026",
        "question": "How much time have you been using the product? ",
        "description": null,
        "type": "multiple_choice",
        "max_length": null,
        "mandatory": null,
        "position": "2",
        "picture": null,
        "random": null,
        "range_from": null,
        "range_to": null,
        "other": null,
        "alerts": null,
        "alert_words": null,
        "options": [
            {
                "id": "1884929",
                "option": "Less than 1 week",
                "thumbnail": null,
                "alert": null
            },
            {
                "id": "1884930",
                "option": "Between 1 week and 1 month",
                "thumbnail": null,
                "alert": null
            },
        ]
    }

Webhooks

Use webhooks to be notified when a user responds to a campaign in real time.

The APIs can send notifications to your application when a user responds to any of your campaigns at the exact moment that it does.

This is very useful for cases where you need to update your own database with the responses from your users without the need of recurring to the APIs to obtain that information.

You can register your URLs where the notifications will be sent when each action happens.

A notification via HTTP POST will be sent to this URL with all of the information gathered from the response of a user.

When to use Webhooks

Webhooks are only necessary to obtain information behind the scene in real time.

You can use webhooks to:

  • Save the responses of your users at the exact moment as they answer.
  • Send an email to users when they answer a campaign.
  • Be notified via PUSH notification to your mobile device through third-party applications.
  • Generate your own reports in your application.

Configuration

You can configure your webhooks in the API section in your dashboard.

In the Webhooks block click on “Create Webhook”. Add the URLs where you want to redirect the notifications and save your changes.

You can send test notifications to configure the endpoint from your side.

You can enter any URL that you want, but it’s strongly recommended that your endpoints are dedicated to receive the information from the APIs.

Receiving a Webhook notification

Creating a Webhook endpoint in your server is no different to creating any other page in your website.

With PHP you should create a new .php archive destined to receive the information and return an answer.

Data sent by webhooks will be in JSON format. You will have to process it and return a 200 status to notify that the message has been successfully received.


    {
        "campaign": {
            "id": "55482",
            "project_name": "Product test",
            "url": "product-test",
            "url_complete": "https%3A%2F%2Fsupport.surveykiwi.com%2Fproduct-test"
        },
        "participant": {
            "id": "1840844",
        },
        "hiddenfields": {
            "name": "Sergei",
            "email": "sergei@google.com",
        },
        "questions": [
            {
                "id": "542036",
                "question": "To start with, choose your gender",
                "description": "If you don't want to answer this question you can just click NEXT.",
                "answers": [
                    {
                        "id": "11931336",
                        "text": "Man",
                        "original_answer": "Man",
                        "picture": "https://d3ejpfy8d58pjw.cloudfront.net/campaigns/5f4cfb3f5a555_6e48f2c839ab63c6d7710f9ea4d13bc9.png",
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542026",
                "question": "How much time have you been using the product? ",
                "description": null,
                "answers": [
                    {
                        "id": "11931337",
                        "text": "Less than 1 week",
                        "original_answer": "Less than 1 week",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542035",
                "question": "What was your first impression with the product?",
                "description": null,
                "answers": [
                    {
                        "id": "11931338",
                        "text": "Very positive",
                        "original_answer": "Very positive",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542027",
                "question": "From the following, select any brands that you have bought or tried in the past. ",
                "description": null,
                "answers": [
                    {
                        "id": "11931339",
                        "text": "BRAND 2",
                        "original_answer": "BRAND 2",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                    {
                        "id": "11931340",
                        "text": "BRAND 3",
                        "original_answer": "BRAND 3",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                    {
                        "id": "11931341",
                        "text": "BRAND 4",
                        "original_answer": "BRAND 4",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                    {
                        "id": "11931342",
                        "text": "BRAND 5",
                        "original_answer": "BRAND 5",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542028",
                "question": "When you bought the product, did you analyze any other brands or just our product? ",
                "description": null,
                "answers": [
                    {
                        "id": "11931343",
                        "text": "I analyzed several brands",
                        "original_answer": "I analyzed several brands",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542029",
                "question": "How frecuently do you use the product?",
                "description": null,
                "answers": [
                    {
                        "id": "11931344",
                        "text": "More than once a day",
                        "original_answer": "More than once a day",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542030",
                "question": "The following questions will be regarding attributes and characteristics of the product.",
                "description": null,
                "answers": [],
            },
            {
                "id": "542031",
                "question": "Which of the following was the most important characteristic for you to decide to acquire the product?",
                "description": "Choose only the MOST important one.",
                "answers": [
                    {
                        "id": "11931345",
                        "text": "Design",
                        "original_answer": "Design",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542032",
                "question": "Which is you current <b>general satisfaction</b> level with the product? ",
                "description": null,
                "answers": [
                    {
                        "id": "11931346",
                        "text": "Completely satisfied",
                        "original_answer": "Completely satisfied",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542033",
                "question": "Would you recommend this product to a friend who is looking for a product inside this category?",
                "description": null,
                "answers": [
                    {
                        "id": "11931347",
                        "text": "10",
                        "original_answer": "10",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
            {
                "id": "542034",
                "question": "If you could change something about the product, what would it be?",
                "description": null,
                "answers": [
                    {
                        "id": "11931348",
                        "text": "Perfect product. I will definitely continue using it",
                        "original_answer": "Perfect product. I will definitely continue using it",
                        "picture": null,
                        "score": null,
                        "alert": null,
                        "option_type": "regular"
                    },
                ]
            },
        ],
        "thankyou_screen": {
            "id": "91138",
            "type": "custom",
            "title": "Thank you for your feedback!",
            "description": "Your information help us improve the quality of our products and new features.",
            "button_text": null,
            "button_url": null,
            "picture": "",
            "video": null,
            "show_responses": null
        },
        "created_at": "2021-10-06T12:12:32-0300",
        "finished_at": "2021-10-06T12:13:10-0300",
        "duration": 38,
        "score": 0.00,
    }

Responding to the Webhook

To notify us that your server has received the information sent, your endpoint will have to return a 200 status (HTTP status code)

All status outside of the range of 200, including the codes 3xx, will indicate that the information sent has failed and that you didn’t receive the information.

This means that a redirect or a “Not modified” type response will be considered as a failure.

Any other information included in the header or in the body of the response will be ignored.

In your dashboard, in the APIs section, you will be able to obtain information and check out the history of the events that have been sent to your endpoints.

Checking the Webhook signature

The Webhooks sent to your endpoints will be signed. A signature in the header SK-Signature will be included in each sending. This will help you to validate that the data sending has been sent from our platform and not third parties.

Before being able to validate the signatures you will have to take note of them in the panel where your webhooks are located.

Preventing forwarding attacks

A forwarding attack is when a valid sending with its corresponding signature is intercepted and is forward. To prevent these attacks, a timestamp will be added in the header SK-Signature. In this way you will be able to check if the signature is valid by analyzing the time that has passed compared with the timestamp sent.

Verifying signatures

The header SK-Signature contains a timestamp and a signature. The timestamp is prefixed by a t=, and the signature is prefixed by a scheme. The scheme starts with a v followed by an entire number. At this moment the only valid number is 1, so the valid scheme will be v1

SK-Signature: \
    t=1539794213,
    v1=720c0195d5fc0d6dc06accf258d3aaf6165a729efbda7f3628d54803576e2c9e