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>' \
  --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>' \
  --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"
},
]                                    
                                    
Share Survey
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
curl --request PUT \
  --url 'https://api.surveysparrow.com/v1/shares/email/{share_id}' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "contacts": [
    "john@example.com"
  ],
"lists": [
"Sales"
]
}'                                    
                                    
204 No content