Overview

Introduction

SurveySparrow API allows you to integrate third party applications in your enterprise ecosystem and helps you to automate workflows like, sending a survey when a ticket is closed or a employee leaves the organisation.

Request & Response Format

SurveySparrow API accepts HTTPS requests with JSON Arguments. The response will be in JSON format. Our Authentication is based on OAuth 2.0 and you can pass your access token over Authorization header as "bearer token"

Authentication

SurveySparrow uses OAuth 2.0 for Authentication . You can generate your access token under Settings → Apps & Integrations . You need to use the generated access token in request header as "bearer token" (-H "Authorization: Bearer Your_ACCESS_TOKEN ")

Generate Access Token

You can Generate Access Token using the following steps.

  1. Login to your surveysparrow account and go to Settings → Apps & Integrations
  2. Create a Private App
  3. Enter Name, Description, select scope and generate the access token
  4. Copy and keep the access token in a safe place (Access token will be displayed only once and you may need to re-generate if you misplaced)
  5. Save your app and you are good to start developing your private app
Scopes

While creating an app you can define the scope or privilege for the API token to communicate with your surveysparrow account. Following are the available scopes and permissions currently supported in SurveySparrow API.

ScopePermission
View ContactsList Contacts
Manage ContactsCreate Contacts, Update Contacts
View Contact ListsList Contact Lists
Manage Contact ListCreate Contact List, Update Contact List
View SurveyList Surveys
View ResponsesList Responses
Manage Share SurveyUpdate Share
Error Handling

SurveSparrow uses standard HTTP status codes like 2xx for success and 4xx for failure . Please refer the following table for status codes.

Status CodePermission
200 OKRequest is successful
202 AcceptedRequest accepted but it is queued or processing
400 Bad RequestRequest has missing required parameters or validation errors
401 UnauthorizedBad Token or missing token
403 ForbiddenAccess denied for the requested resource
404 Not FoundThe requested resource doesn’t exist
409 ConflictRequest conflicts with another, trying to create already existing resource
429 Too Many RequestsApi request limit exceeded
500 Internal Server ErrorSomething went wrong in Surveysparrow

Some of the error code above will give you a deeper level of information just like below

Error TypeDescription
missing_scopeToken doesn’t has the requested resource scope
backend_errorError in Surveysparrow servers
already_existThe resource trying to create already exist
permission_deniedYou don’t have the access rights for requested resource
not_foundThe requested resource is not available in the system.
not_activeResource is not active now, so you can’t perform the operation
limit_exceededYou have reached your hourly quota.
disabledThe app or integration is disabled by the creator.
bad_tokenDue to any of the following reasons
Invalid token,
Token expired,
user revoked the access
Rate Limit

Currently our API is rate limited at 1000 requests per hour. Once you exceed this, API responds with an error code 429 (Too Many requests)

Pagination

You can use our pagination with maxResults and page parameter to navigate when your list exceed our default Max-Results . Currently our default Max-Results is set at 50. When you exceed this you can paginate using Page params (Ex:- https://api.surveysparrow.com/v1/contacts?maxResults=100&page=2)

Passed as Query Parameter
NameDescription
maxResultsNo of results needed in a request
pagePage No

For all GET calls you can use option params to paginate.

API Explorer

Audience
Create Contact
POST

https://api.surveysparrow.com/v1/contacts

Arguments for API Call
NameDescriptionTypeMandatory
emailEmail of the contactstringYes
nameName of the contactstringNo
phonePhone number of the contactstringNo
mobileMobile number of the contactstringNo
jobTitleJob Title of the contactstringNo
curl --request POST \
  --url https://api.surveysparrow.com/v1/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \

  --data '{
  "email": "john@example.com",
  "name":"John Joseph",
  "phone": "91234567833",
  "mobile": "1653452783",
  "jobTitle": "Manager"
}'
                                    
{
  "id": 33,
  "email": "john@example.com",
  "phone": "91234567833",
  "mobile": "1653452783",
  "active": true,
  "jobTitle": "Manager",
  "unsubscribed": false,
  "name": "John Joseph"
}
View Contact
GET

https://api.surveysparrow.com/v1/contacts

Response Attributes
NameDescriptionType
idID of the Contactinteger
emailEmail of the contactstring
nameName of the Contactstring
phonePhone No: of the Contactstring
mobileMobile No: of the Contactstring
jobTitleJob Title of the Contactstring
activeStatus of contact is active or notboolean
unsubscribedStatus of the contact is unsubscribed or notboolean
curl --request GET \
  --url https://api.surveysparrow.com/v1/contacts\
  --header 'Authorization: Bearer <token>' 
                                    
[{
  "id": 33,
  "email": "john@example.com",
  "phone": "91234567833",
  "mobile": "1653452783",
  "active": true,
  "jobTitle": "Manager",
  "unsubscribed": false,
  "name": "John Joseph"
},
 { "id": 34,
  "email": "denny@example.com",
  "phone": "8765467890",
  "mobile": "1320559878",
  "active": true,
  "jobTitle": "Manager",
  "unsubscribed": false,
  "name": "Denny Alan"
},
]
                                    
                                    
Create Contacts in Contact List
POST

https://api.surveysparrow.com/v1/contactlist/{contact_list_id}/
contacts

Path Parameters
NameDescription
contact_list_idID of the contact list
Response Attribute
StatusDescription
createdContacts Created
pendingPending will come if No: of Contacts is more than 20
curl --request POST \
  --url https://api.surveysparrow.com/v1/contactlist/{contact_list_id}/contacts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '[{
  "email": "john@example.com",
  "name":"John Joseph",
  "phone": "91234567833",
  "mobile": "1653452783",
  "jobTitle": "Manager"
},
{"email": "denny@example.com",
  "name": "Denny Alan",
  "phone": "8765467890",
  "mobile": "1320559878",
  "jobTitle": "Manager"
}]'     
                                  
{status:’created’}                                    
                                    
View Contact List
GET

https://api.surveysparrow.com/v1/contactlist/{contact_list_id}/
contacts

Path Parameters
NameDescription
contact_list_idID of the Contact List
Response Attributes
NameDescriptionType
idID of the Contactinteger
emailEmail of the contactstring
nameName of the Contactstring
phonePhone No: of the Contactstring
mobileMobile No: of the Contactstring
jobTitleJob Title of the Contactstring
activeStatus of contact is active or notboolean
unsubscribedStatus of the contact is unsubscribed or notboolean
curl --request GET \
  --url https://api.surveysparrow.com/v1/contactlist/{contact_list_id}/contacts\
  --header 'Authorization: Bearer <token>'                                    
                                    
[{
  "id": 33,
  "email": "john@example.com",
  "phone": "91234567833",
  "mobile": "1653452783",
  "active": true,
  "jobTitle": "Manager",
  "unsubscribed": false,
  "name": "John Joseph"
},
 { "id": 34,
  "email": "denny@example.com",
  "phone": "8765467890",
  "mobile": "1320559878",
  "active": true,
  "jobTitle": "Manager",
  "unsubscribed": false,
  "name": "Denny Alan"
}]                                    
                                    
Surveys
View Surveys
GET

https://api.surveysparrow.com/v1/surveys

Options: Passed as Query Parameters
NameDescription
maxResultsNo of results needed in a request
pagePage No
curl --request GET \
  --url https://api.surveysparrow.com/v1/surveys\
  --header 'Authorization: Bearer <token>'                               
                                    
{
  "surveys": [
    {
      "id": 24,
      "name": "Interview Feedback Survey",
      "archived": false,
      "surveyType": "ClassicForm"
    },
    {
      "id": 16,
      "name": "Employee Satisfaction Survey",
      "archived": false,
      "surveyType": "ClassicForm"
    }
  ],
  "hasNextPage": false
}
                                    
View Submissions
GET

https://api.surveysparrow.com/v1/surveys/{survey_id}/submissions

Path Parameters
NameDescription
survey_idID of the survey
Options: Passed as Query Parameters
NameDescription
maxResultsNo of results needed in a request
pagePage No
Response Attributes
NameDescriptionType
submissionsSubmissions of the surveyArray
answersAnswers of a submissionArray
questionsQuestions of the surveyArray
curl --request GET \
--url https://api.surveysparrow.com/v1/surveys/{survey_id}/submissions \
--header 'Authorization: Bearer <token>'                                   
                                    
{
   "submissions":[
      {
         "id":209,
         "completed_time":"2018-04-05T09:35:01.000Z",
         "survey_id":6,
         "contact": {
            "id": 3,
            "firstName": "Jamie",
            "lastName": "Foxx",
            "email": "jamiefoxx@example.com",
            "phone": "91234567833",
            "mobile": "1653452783",
         }
         "answers":[
            {
               "answer":8,
               "question":" How much you like this editor",
               "question_id":43
            }
        ]
      }
   ],
   "hasNextPage":false,
   "questions":[
      {
         "question":" How much you like this editor",
         "id":43
      }
   ]
}
                                    
View Submission
GET

https://api.surveysparrow.com/v1/surveys/{survey_id}/submissions/{id}

Path Parameters
NameDescription
survey_idID of the Survey
idID of the Submission
curl --request GET \
  --url https://api.surveysparrow.com/v1/surveys/{survey_id}/submissions/{id}\
  --header 'Authorization: Bearer <token>'                                
                                    
{
  "id": 1873,
  "completedTime": "2019-05-10T12:54:03.000Z",
  "survey_id": 337,
  "answers": [
    {
      "answer": "Jane Doe",
      "question": " Enter your Name",
      "question_id": 2432
    },
    {
      "answer": "jane.doe@gmail.com",
      "question": " Please share your Email",
      "question_id": 2433
    },
    {
      "answer": 9,
      "question": "Please rate us on a scale of 1-10",
      "question_id": 2434
    }
  ]
}
                                    
View Questions
GET

https://api.surveysparrow.com/v1/surveys/{id}/questions

Path Parameters
NameDescription
idID of the Survey
Options: Passed as Query Parameters
NameDescription
maxResultsNo of results needed in a request
pagePage No
curl --request GET \
  --url https://api.surveysparrow.com/v1/surveys/{id}/questions\
  --header 'Authorization: Bearer <token>'                               
                                    
{
  "questions": [
    {
      "id": 2433,
      "rtxt": {
        "blocks": [
          {
            "key": "dhbar",
            "text": "Please share your Email",
            "type": "unstyled",
            "depth": 0,
            "inlineStyleRanges": [],
            "entityRanges": [],
            "data": {}
          }
        ],
        "entityMap": {}
      },
      "type": "EmailInput",
      "properties": {
        "data": {}
      },
      "parent_question_id": null,
      "section": {
        "position": "0.000000000000000"
      }
    },
    {
      "id": 2434,
      "rtxt": {
        "blocks": [
          {
            "key": "dhbar",
            "text": "Please rate us on a scale of 1-10",
            "type": "unstyled",
            "depth": 0,
            "inlineStyleRanges": [],
            "entityRanges": [],
            "data": {}
          }
        ],
        "entityMap": {}
      },
      "type": "OpinionScale",
      "properties": {
        "data": {
          "min": "builder.opinion_scale.min",
          "max": "builder.opinion_scale.max",
          "step": 10,
          "start": 1
        }
      },
      "parent_question_id": null,
      "section": {
        "position": "1.000000000000000"
      }
    }
  ],
  "hasNextPage": false
}

                                    
View Webhooks of a Survey
GET

https://api.surveysparrow.com/v1/surveys/{survey_id}/webhooks

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
maxResultsNo of results needed in a request
pagePage No
curl --request GET \
  --url https://api.surveysparrow.com/v1/surveys/{survey_id}/webhooks \
  --header 'Authorization: Bearer <token>'                         
                                    
{
  "webhooks": [
    {
      "id": 1,
      "name": "Interview Survey Webhook",
      "url": "http://webhook.site/48bd9aac-ebc8-43c1-8f9f-22a780a2ba59",
      "eventType": "submission_completed",
      "objectType": "survey",
      "objectId": 16,
      "httpMethod": "POST",
      "headers": [
        {
          "key": "Content-Type",
          "value": "application/json"
        }
      ],
      "properties": {
        "payload": "{\n  \"Q1\": \"{question_96}\",\n  \"survey_id\": \"{survey_id}\",\n  \"Q2\": \"{question_122}\"\n}"
      },
      "disabled": false,
      "type": "application"
    }
  ],
  "hasNextPage": false
}
                                    
Shares
POST

https://api.surveysparrow.com/v1/surveys/{survey_id}/share/link

Path Parameters
NameDescription
survey_idID of the Survey
curl --request POST \
  --url https://api.surveysparrow.com/v1/surveys/{survey_id}/share/link \
  --header 'Authorization: Bearer <token>'                            
                                    
{
  "url": "https://betterworld.surveysparrow.com/s/Employee-Survey/tt-69bd57",
  "id": 28,
  "shareType": "LINK"
}

                                    
Send Email Surveys
PUT

https://api.surveysparrow.com/v1/shares/email/{share_id}

Path Parameters
NameDescription
share_idID of the share
Arguments for API Call
NameDescriptionTypeMandatory
contactsEmail of the ContactArrayNo
listsName of the Contact ListArrayNo
customParamsCustom Variables for the SurveyObjectNo
curl --request PUT \
  --url 'https://api.surveysparrow.com/v1/shares/email/{share_id}' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \

  --data '{
  "contacts": ["john@example.com"],
  "lists": [ "Sales" ],
  "customParams": {
    "team": "Engineering",
    "manager": "Jane Doe",
  }
}'                                    
                                    
204 No content                                    
                                    
View Shares
GET

http://api.surveysparrow.com/v1/surveys/{survey_id}/shares

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
maxResultsNo of results needed in a request
pagePage No
curl --request GET \
  --url https://api.surveysparrow.com/v1/surveys/{survey_id}/shares \
  --header 'Authorization: Bearer <token>'                           
                                    
{
  "shares": [
    {
      "id": 9,
      "name": "Web Link Share",
      "type": "LINK",
      "status": "ACTIVE",
      "subject": "LINK Share",
      "properties": {},
      "schedule": null
    },
    {
      "id": 25,
      "name": "Web Link Share - 16 May 2019 16:30",
      "type": "LINK",
      "status": "ACTIVE",
      "subject": "LINK Share",
      "properties": {},
      "schedule": null
    }
  ],
  "hasNextPage": false
}
                         
                                    
Webhooks
View Webhooks
GET

https://api.surveysparrow.com/v1/webhooks

Options: Passed as Query Parameters
NameDescription
maxResultsNo of results needed in a request
pagePage No
curl --request GET \
  --url https://api.surveysparrow.com/v1/webhooks \
  --header 'Authorization: Bearer <token>'                               
                                    
{
  "webhooks": [
    {
      "id": 1,
      "name": "Interview Survey Webhook",
      "url": "http://webhook.site/48bd9aac-ebc8-43c1-8f9f-22a780a2ba59",
      "eventType": "submission_completed",
      "objectType": "survey",
      "objectId": 16,
      "httpMethod": "POST",
      "headers": [
        {
          "key": "Content-Type",
          "value": "application/json"
        }
      ],
      "properties": {
        "payload": "{\n  \"Q1\": \"{question_96}\",\n  \"survey_id\": \"{survey_id}\",\n  \"Q2\": \"{question_122}\"\n}"
      },
      "disabled": false,
      "type": "application"
    },
    {
      "id": 2,
      "name": "Employee Satisfaction Webhook",
      "url": "http://webhook.site/48bd9aac-ebc8-43c1-8f9f-22a780a2ba59",
      "eventType": "submission_completed",
      "objectType": "survey",
      "objectId": 17,
      "httpMethod": "POST",
      "headers": [
        {
          "key": "Content-Type",
          "value": "application/json"
        }
      ],
      "properties": {},
      "disabled": false,
      "type": "application"
    }
  ],
  "hasNextPage": false
}
                                    
Add Webhook
POST

https://api.surveysparrow.com/v1/webhooks

Arguments for API Call
NameDescriptionTypeMandatory
nameName of the WebhookStringNo
urlURL of the WebhookStringYes
surveyIdSurvey ID of Survey for the WebhookIntegerYes
httpMethodRequest TypeStringYes
headersHeaders of the RequestArrayYes
payloadPayload of the WebhookObjectNo
curl --request POST \
  --url https://api.surveysparrow.com/v1/webhooks \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \

  --data '{
    "name": "Webhook",
    "url": "http://webhook.site/1ddef940-266c-4b4b-b2c8-fb7d608d24f6",
    "surveyId": 337,
    "httpMethod": "POST",
    "headers": [{"key": "Content-Type", "value": "application/json"}],
    "payload": {
        "survey_id": "{survey_id}",
        "Q1":"{question_2432}"
    }
  }'                              
                                    
{
  "id": 5,
  "name": "Webhook",
  "url": "http://webhook.site/1ddef940-266c-4b4b-b2c8-fb7d608d24f6",
  "eventType": "submission_completed",
  "objectType": "survey",
  "objectId": 337,
  "httpMethod": "POST",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "properties": {
    "payload": "{\"survey_id\":\"{survey_id}\",\"Q1\":\"{question_2432}\"}"
  },
  "disabled": false,
  "type": "application"
}
                         
                                    
Update Webhook
PUT

https://api.surveysparrow.com/v1/webhooks/{id}

Path Parameters
NameDescription
idID of the Webhook
Arguments for API Call
NameDescriptionTypeMandatory
nameName of the WebhookStringNo
urlURL of the WebhookStringNo
httpMethodRequest TypeStringNo
headersHeaders of the RequestArrayNo
payloadPayload of the WebhookObjectNo
curl --request PUT \
  --url https://api.surveysparrow.com/v1/webhooks/{id}\
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Webhook v2",
    "payload": {
      "survey_id": "{survey_id}",
      "Q1": "{question_2432}",
      "Q2": "{question_2433}",
      "submission_id": "{submission_id}"
    }
  }'                                
                                    
{
  "id": 26,
  "name": "Webhook v2",
  "url": "http://webhook.site/48bd9aac-ebc8-43c1-8f9f-22a780a2ba59",
  "eventType": "submission_completed",
  "objectType": "survey",
  "objectId": 337,
  "httpMethod": "GET",
  "headers": [
    {
      "key": "Content-Type",
      "value": "application/json"
    }
  ],
  "properties": {
    "payload": "{\"survey_id\":\"{survey_id}\",\"Q1\":\"{question_2432}\",\"Q2\":\"{question_2433}\",\"submission_id\": \"{submission_id}\"}"
  },
  "disabled": false,
  "type": "application"
}
                                    
Delete Webhook
DELETE

https://api.surveysparrow.com/v1/webhooks/{id}

Path Parameters
NameDescription
idID of the Webhook
curl --request DELETE \
  --url https://api.surveysparrow.com/v1/webhooks/{id}\
  --header 'Authorization: Bearer <token>'                             
                                    
204 No Content