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

Our API rate is limited to 120 calls per hour and 1000 requests per day. Once you exceed this, API responds with an error code 429 (Too Many requests). Please get in touch with the Support or Sales team for additional API 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"
}]
                                    
Custom Property (Variables)
Get all Custom Property of the survey
GET

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

Path Parameters
NameDescriptionRequiredDataType
survey_idID of the SurveyYesNumber
curl  --request GET \
--url ' https://api.surveysparrow.com/v1/surveys/25/variables' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
                                    
[
   {
       "id": 16,
       "name": "UID",
       "label": "UID",
       "type": "STRING",
       "description": "",
       "created_at": "2020-08-12T15:35:52.802Z",
       "updated_at": "2020-08-12T15:35:52.802Z",
       "deleted_at": null,
       "account_id": 2,
       "survey_id": 25
   },
   {
       "id": 17,
       "name": "developer",
       "label": "Developer",
       "type": "NUMBER",
       "description": "",
       "created_at": "2020-08-12T15:36:18.297Z",
       "updated_at": "2020-08-12T15:36:18.297Z",
       "deleted_at": null,
       "account_id": 2,
       "survey_id": 25
   }
]

                                    
Create a Custom Property
POST

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

Path Parameters
NameDescriptionRequiredDataTypeAllowed Values
survey_idId of the surveyYesNumber
Other Arguments
NameDescriptionRequiredDataTypeAllowed Values
labelCustom property labelYesString
nameName of the custom property Used to pass values to a value to the variable (API Identifier)YesString
descriptionSmall note about the variableNoString
typeThe data type of the variableYesStringSTRING Or NUMBER Or DATE

curl  --request POST \
--url ' https://api.surveysparrow.com/v1/surveys/25/variables' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
	--data {
       "label": "'Deportment'",
       "name": "deportment",
       "type": "STRING"
}

                                

{
   "id": 18,
   "label": "Deportment'',
   "name": "deportment",
   "type": "STRING",
   "survey_id": 25,
   "account_id": 2,
   "updated_at": "2020-08-12T17:52:15.447Z",
   "created_at": "2020-08-12T17:52:15.447Z",
   "description": null,
   "deleted_at": null
}

                                
Delete a Custom Property
DELETE

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

Path Parameters
NameDescriptionRequiredDataType
survey_idId of the surveyYesNumber
variable_idId of the custom propertyYesNumber

curl  --request DELETE \
--url 'https://api.surveysparrow.com/v1/surveys/21/variables/49' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'

                                

{ "success": true }

                                
Workspace
View Workspaces
GET

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

Options: Passed as Query Parameters
NameDescription
maxResultsNo of results needed in a request
pagePage No
curl --request GET \
  --url https://api.surveysparrow.com/v1/workspaces \
  --header 'Authorization: Bearer <token>'
                                    
{
  "workspaces": [{
      "id": 9056,
      "name": "General",
      "description": null,
      "auto_created": true,
      "visibility": "ALL",
      "teams": [{
        "id": 53,
        "name": "Developer",
        "description": null
      }],
      "surveys": [{
          "id": 31514,
          "name": "test",
          "surveyType": "Conversational",
        },
        {
          "id": 45534,
          "name": "COVID-19 Employee Evaluation Checklist",
          "surveyType": "ClassicForm",
        },
      ]
    },
    {
      "id": 9057,
      "name": "Customer Pulse",
      "description": null,
      "auto_created": false,
      "visibility": "ALL",
      "teams": [],
      "surveys": [{
        "id": 31755,
        "name": "Patient Feedback Survey",
        "surveyType": "ClassicForm",
      }]
    }
  ]
}
                                    
View Workspace
GET

https://api.surveysparrow.com/v1/workspaces/{workspace_id}

Options: Passed as Query Parameters
NameDescription
idID of the Workspace
curl --request GET \
  --url https://api.surveysparrow.com/v1/workspaces/{workspace_id} \
  --header 'Authorization: Bearer <token>'
                                    
{
  "workspace": {
    "id": 9057,
    "name": "Customer Pulse",
    "description": null,
    "auto_created": false,
    "visibility": "TEAM",
    "teams": [{
      "id": 52,
      "name": "Support",
      "description": null
    }],
    "surveys": [{
      "id": 31755,
      "name": "Patient Feedback Survey",
      "surveyType": "ClassicForm"
    }]
  }
}
                                    
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
}
                                    
Surveys
View Survey
GET

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

Options: Passed as Query Parameters
NameDescription
idID of the Survey
curl  --request GET \
  --url 'https://api.surveysparrow.com/v1/surveys/{id}' \
  --header 'Content-Type: application/json'
  --header 'Authorization: Bearer <token>'
                                    
{
	"id": 33089,
	"name": "Customer Satisfaction Survey",
	"welcome_rtxt": {
		"blocks": [
			{
				"key": "1hern",
				"text": "Hello, got a moment to share some feedback? 😁 ",
				"type": "unstyled",
				"depth": 0,
				"inlineStyleRanges": [],
				"entityRanges": [],
				"data": {}
			}
		],
		"entityMap": {}
	},
	"welcomeDescription": null,
	"welcomeScreenYesButtonText": "Sure, ask!",
	"thankyou_json": [
		{
			"message": {
				"entityMap": {},
				"blocks": [
					{
						"key": "1hern",
						"text": "Thank you for your time!",
						"type": "unstyled",
						"depth": 0,
						"inlineStyleRanges": [],
						"entityRanges": [],
						"data": {}
					}
				]
			},
			"redirectBoolean": false,
			"descriptionBoolean": true,
			"description": {
				"entityMap": {},
				"blocks": [
					{
						"key": "1hern",
						"text": "",
						"type": "unstyled",
						"depth": 0,
						"inlineStyleRanges": [],
						"entityRanges": [],
						"data": {}
					}
				]
			},
			"branding": true
		}
	],
	"archived": false,
	"visibility": "Public",
	"surveyType": "Conversational",
	"templateName": "Customer Satisfaction",
	"properties": {
		"autosizeHeading": true,
		"progress": {
			"builderCompleted": true,
			"designCompleted": true,
			"shareCompleted": true,
			"integrationCompleted": true,
			"reportsCompleted": true
		},
		"surveyRandomiser": false
	},
	"published": true,
	"euiVersion": 1,
	"phishing": false,
	"created_at": "2020-01-13T12:29:48.597Z",
	"updated_at": "2020-02-13T07:27:47.755Z",
	"deleted_at": null,
	"account_id": 13856,
	"user_id": 46136,
	"survey_folder_id": 37471,
	"thankyou_template_id": null,
	"theme_id": 8054,
	"customParams": [
		{
			"id": 3162,
			"name": "AccountId",
			"desc": null,
			"created_at": "2020-01-13T12:29:48.686Z",
			"updated_at": "2020-01-13T12:29:48.686Z",
			"deleted_at": null,
			"account_id": 13856,
			"survey_id": 33089
		},
		{
			"id": 3163,
			"name": "ContactId",
			"desc": null,
			"created_at": "2020-01-13T12:29:48.686Z",
			"updated_at": "2020-01-13T12:29:48.686Z",
			"deleted_at": null,
			"account_id": 13856,
			"survey_id": 33089
		},
		{
			"id": 3164,
			"name": "CaseId",
			"desc": null,
			"created_at": "2020-01-13T12:29:48.686Z",
			"updated_at": "2020-01-13T12:29:48.686Z",
			"deleted_at": null,
			"account_id": 13856,
			"survey_id": 33089
		}
	]
}

                                    
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
}
                                    
Survey Settings
Get Survey settings
GET

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

Path Parameters
NameDescriptionRequired
survey_idId of the surveyYes

curl  --request GET \
--url 'https://api.surveysparrow.com/v1/surveys/21/settings' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'

                                

{
   "id": 23,
   "indicator": "PERCENTAGE",
   "anonymousResponses": true,
   "disableContactTracking": false,
   "redunantResponses": false,
   "editResponse": true,
   "partialSubmission": false,
   "partialNotification": true,
   "sendResponsesMail": true,
   "copyOfResponse": false,
   "trackIP": false,
   "responseLimit": 0,
   "cutOffDate": null,
   "blacklistedIPs": null,
   "urlPath": "API-TEST-12-aug-after-2",
   "overridden": false,
   "analytics": {},
   "selfResponse": {},
   "created_at": "2020-08-12T11:26:19.415Z",
   "updated_at": "2020-08-12T13:38:27.603Z",
   "deleted_at": null,
   "account_id": 2,
   "survey_id": 21
}

                                
Edit Survey Settings
PUT

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

Path Parameters
NameDescriptionRequiredDataTypeDefault Value
survey_idId of the surveyYesNumber
Other Arguments
NameDescriptionRequiredDataTypeDefault Value
partialSubmissionAllow partial submission to the surveyNoBooleanTrue
editResponseAllow user to edit and resubmit the surveyNoBooleanFalse
anonymousResponsesSmall note about the variableNoBooleanFalse

curl  --request PUT \
--url ' https://api.surveysparrow.com/v1/surveys/21/settings' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>>'
	--data {
       "partialSubmission": false
}

                                

{
 	"success": true
}

                                
Create a Survey
POST

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

Other Arguments
NameDescriptionRequiredDataTypeDefault ValueAllowed values
nameName of the surveyYesString
surveyTypeType of the surveyYesStringClassicForm
workspace_idId of the workspaceNoNumberWorkspace “General” will be taken
theme_idName of the templateNoNumberNull
welcomeScreenYesButtonTextWelcome screen button labelNoStringSure, ask.
welcomeDescriptionEnabledIt will enable welcome screen descriptionNoBooleanFalse
welcomeTextAdd a welcome page to the survey. Welcome screen titleNoString
welcomeDescriptionWelcome screen descriptionNoString
thankyou_jsonAdd a thank you page to the surveyNoArray

curl  --request POST \
--url 'https://api.surveysparrow.com/v1/surveys' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
	--data {
   "name": "TEST Survey",
   "surveyType": "ClassicForm",
   "welcomeText”: "Welcome to the survey $Param_department", // Example for passing variables
   "workspace_id":1069,
   "theme_id": 18119,
   "welcomeDescriptionEnabled": true,
   "welcomeScreenYesButtonText": "start the survey",
   "welcomeDescription": "this is description",
   "thankyou_json":[
 {
   "message": "Thank you for your time", // Here you can pass variable
   "branding": false,
   "description": "Thank you page description" // Here you can pass variable
 },{
   "redirectBoolean": true,
   "redirect":"https://surveysparrow.com"
 }
]
}

                                

{
   "name": "API TEST 13-aug 13 tt redirect final 2",
   "surveyType": "ClassicForm",
   "welcome_rtxt": {
       "entityMap": {},
       "blocks": [
           {
               "key": "1hern",
               "text": "Welcome to the survey",
               "type": "unstyled",
               "depth": 0,
               "inlineStyleRanges": [],
               "entityRanges": [],
               "data": {}
           }
       ]
   },
   "survey_folder_id": 1069,
   "templateName": "Job Satisfaction",
   "welcomeDescriptionEnabled": true,
   "welcomeScreenYesButtonText": "start the survey",
   "welcomeDescription": "this is description",
   "thankyou_json": [
       {
           "message": {
               "entityMap": {},
               "blocks": [
                   {
                       "key": "1hern",
                       "text": "Thank you page now",
                       "type": "unstyled",
                       "depth": 0,
                       "inlineStyleRanges": [],
                       "entityRanges": [],
                       "data": {}
                   }
               ]
           },
           "branding": false,
           "description": {
               "entityMap": {},
               "blocks": [
                   {
                       "key": "1hern",
                       "text": "Thank you page description",
                       "type": "unstyled",
                       "depth": 0,
                       "inlineStyleRanges": [],
                       "entityRanges": [],
                       "data": {}
                   }
               ]
           }
       },
       {
           "redirectBoolean": true,
           "redirect": "https://surveysparrow.com",
           "message": {
               "entityMap": {},
               "blocks": [
                   {
                       "key": "1hern",
                       "text": "Thank you for your time!",
                       "type": "unstyled",
                       "depth": 0,
                       "inlineStyleRanges": [],
                       "entityRanges": [],
                       "data": {}
                   }
               ]
           },
           "description": {
               "entityMap": {},
               "blocks": [
                   {
                       "key": "1hern",
                       "text": "",
                       "type": "unstyled",
                       "depth": 0,
                       "inlineStyleRanges": [],
                       "entityRanges": [],
                       "data": {}
                   }
               ]
           }
       }
   ],
   "theme_id": 194,
   "account_id": 369,
   "survey_folder_name": "Customer Pulse",
   "user_id": 481,
   "primaryLanguage": "en",
   "properties": {
       "welcomeDescriptionEnabled": true,
       "autosizeHeading": true,
       "surveyRandomiser": false
   },
   "id": 3943
}

                                
Create a Non-Abstract Section
POST

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

Path Parameters
NameDescriptionRequiredDataTypeDefault Value
survey_idId of the surveyYesNumber
Other Arguments
NameDescriptionRequiredDataTypeDefault Value
nameSection heading or titleYesString
descriptionSection descriptionNoObject
propertiesPass the extra information about a section, like section button labelNoObject
Ex:
"properties": {
    "label": "ccc"
}
label: “Continue”
questionsIt will add questions to this sectionNoArray

curl  --request POST \
--url 'https://api.surveysparrow.com/v1/surveys/24/sections'\
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'
	--data {
   "name": "Welcome to this section", // Here you can pass variable
   "description":"This is section will be based on the leadership quality", // Here you can pass variable
   "properties": {
       "label": "start a this section"
   },
       "questions": [{
           "text": "Please upload your file", // Here you can pass variable
           "type": "FileInput",
           "properties": {
               "data": {
                   "fileTypes": ["image", "doc", "video"]
               }
           }
       },{
           "text": "Please enter your feedback", // Here you can pass variable
           "type": "TextInput",
           "properties": {
               "data": {
                   "type": "MULTI_LINE"
               }
           }
       },{
           "text": "Please give your rating", // Here you can pass variable
           "type": "OpinionScale",
           "properties": {
               "data": {
                   "min": "min label",
                   "max": "max label",
                   "start": 1,
                   "step": 7
               }
           }
       }]
}

                                

{
   "name_rtxt": {
       "blocks": [
           {
               "key": "1hern",
               "text": "Welcome to this section",
               "type": "unstyled",
               "depth": 0,
               "inlineStyleRanges": [],
               "entityRanges": [],
               "data": {}
           }
       ],
       "entityMap": {}
   },
   "desc_rtxt": {
       "blocks": [
           {
               "key": "1hern",
               "text": "This is section is based on the leadership quality",
               "type": "unstyled",
               "depth": 0,
               "inlineStyleRanges": [],
               "entityRanges": [],
               "data": {}
           }
       ],
       "entityMap": {}
   },
   "properties": {
       "data": {
           "label": "start a this section"
       },
       "sectionRandomise": false
   },
   "questions": [
       {
           "rtxt": {
               "blocks": [
                   {
                       "key": "1hern",
                       "text": "Please upload your file",
                       "type": "unstyled",
                       "depth": 0,
                       "inlineStyleRanges": [],
                       "entityRanges": [],
                       "data": {}
                   }
               ],
               "entityMap": {}
           },
           "type": "FileInput",
           "properties": {
               "data": {
                   "fileTypes": [
                       "image",
                       "doc",
                       "video"
                   ]
               }
           },
           "position": 0,
           "survey_id": 24,
           "txt": "",
           "section_id": 119,
           "account_id": 2,
           "id": 146
       },
       {
           "rtxt": {
               "blocks": [
                   {
                       "key": "1hern",
                       "text": "Please enter your feedback",
                       "type": "unstyled",
                       "depth": 0,
                       "inlineStyleRanges": [],
                       "entityRanges": [],
                       "data": {}
                   }
               ],
               "entityMap": {}
           },
           "type": "TextInput",
           "properties": {
               "data": {
                   "type": "MULTI_LINE"
               }
           },
           "position": 1,
           "survey_id": 24,
           "txt": "",
           "section_id": 119,
           "account_id": 2,
           "id": 147
       },
       {
           "rtxt": {
               "blocks": [
                   {
                       "key": "1hern",
                       "text": "Please give your rating",
                       "type": "unstyled",
                       "depth": 0,
                       "inlineStyleRanges": [],
                       "entityRanges": [],
                       "data": {}
                   }
               ],
               "entityMap": {}
           },
           "type": "OpinionScale",
           "properties": {
               "data": {
                   "min": "min label",
                   "max": "max label",
                   "start": 1,
                   "step": 7
               }
           },
           "position": 2,
           "survey_id": 24,
           "txt": "",
           "section_id": 119,
           "account_id": 2,
           "id": 148
       }
   ],
   "account_id": 2,
   "survey_id": 24,
   "name": "Untitled Section",
   "abstract": false,
   "position": 3,
   "id": 119
}

                                
Add a question to the section
POST

https://api.surveysparrow.com/v1/sections/{section_id}/questions

Path Parameters
NameDescriptionRequiredDataTypeAllowed values
section_idId of the sectionYesNumber
Other Arguments
NameDescriptionRequiredDataTypeAllowed values
textQuestion textYesString
typeType of the questionYesStringFileInput Or TextInput Or OpinionScale
descriptionQuestion descriptionNoString
requiredIf it is mandatory question or notNoBooleanTrue
propertiesExtra information can be passed in thisNoObject

Data passed inside this will be varied based on question type (please refer the important hints)

curl  --request POST \
--url ' https://api.surveysparrow.com/v1/sections/119/questions' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>>'
--data {
   "text": "Share your rating", // Here you can pass variable
   "type": "OpinionScale",
   “description”: “This is question will record you opinion”,
   "properties": {
       "data": {
           "min": "Least",
           "max": "Most",
           "start": 0,
           "step": 10
       }
   }
}

                                

{
   "rtxt": {
       "blocks": [
           {
               "key": "1hern",
               "text": "Share your rating",
               "type": "unstyled",
               "depth": 0,
               "inlineStyleRanges": [],
               "entityRanges": [],
               "data": {}
           }
       ],
       "entityMap": {}
   },
   "type": "OpinionScale",
   "properties": {
       "data": {
           "min": "Least",
           "max": "Most",
           "start": 0,
           "step": 10
       }
   },
   "account_id": 2,
   "section_id": 119,
   "txt": "",
   "position": 1,
   "survey_id": 24,
   "id": 150
}

                                
Delete a section
DELETE

https://api.surveysparrow.com/v1/surveys/{section_id}/sections/{section_id}

Path Parameters
NameDescriptionRequiredDataType
survey_idId of the surveyYesNumber
section_idId of the sectionYesNumber

curl  --request DELETE \
--url 'https://api.surveysparrow.com/v1/surveys/28/sections/140'' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'

                                

{
    "success": true
}

                                
Delete a question
DELETE

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

Path Parameters
NameDescriptionRequiredDataType
survey_idId of the surveyYesNumber
question_idId of the questionYesNumber

curl  --request DELETE \
--url 'https://api.surveysparrow.com/v1/surveys/28/questions/78' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'

                                

{
    "success": true
}

                                
Get Theme
GET

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

Path Parameters
NameDescriptionRequiredDataTypeAllowed Values
surveyTypeType of the surveyYesStringConversational Or ClassicForm Or OfflineApp Or NPS Or Employee360

curl  --request DELETE \
--url'https://api.surveysparrow.com/v1/surveythemes?surveyType=ClassicForm' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>'

                                
Important hint
  1. Supported question types: [FileInput,TextInput,OpinionScale]
  2. Question required will be True by default, so if you want to make it as not required pass “required: false

Example:

{
   "rtxt": {
       "text": "Share your rating"
   },
   required: false, // #2 (optional)
   "type": "OpinionScale", // #1
   "properties": {
       "data": {
           "min": "Least",
           "max": "Most",
           "start": 0,
           "step": 10
       }
   }
}


Question Types:

1. OpinionScale:

Key can pass inside the properties.data:

KeyDescriptionDataTypeDefault ValueRequiredAllowed values
minOpinion scale min labelStringLeast LikelyNo
maxOpinion Scale max labelStringMost LikelyNo
startStart value of the opinion scaleNumber0No0 or 1
stepOpinion scale step lengthNumber10No3 to 10


2. TextInput:

Key can pass inside the properties.data:

KeyDescriptionDataTypeDefault ValueRequiredAllowed values
typeType of the textinputStringSINGLE_LINENoSINGLE_LINE Or MULTI_LINE


3. FileInput:

Key can pass inside the properties.data:

KeyDescriptionDataTypeDefault ValueRequiredAllowed values
fileTypesType of the file allowed to uploadArray["image", "doc"]No["image", "doc", "video"]
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
sendLaterInDaysSend an email after a certain number of days.NumberNo
sendLaterSend an email on this date. The date should be in ISO format.DateNo
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",
  },
  "sendLaterInDays": 4,
  "sendLater": "2020-01-07T08:14:55+0000"
}'
                                    
204 No content
                                    
Send Email Surveys (v2)
PUT

https://api.surveysparrow.com/v2/survey/{surveyId}/shares/email/{shareId}

Path Parameters
NameTypeDescription
surveyIdnumberID of the survey
ShareIdnumberID of the share (channel)
Arguments for API Call
NameTypeMandatoryDescription
contactsArray Of emailsNoList of contacts to send the Survey
listsArray Of ContactList namesNoArray of contactList to send the Survey
variablesObjectNoVariables for the Survey
sendLaterInDaysNumberNosendLaterInDays
sendLaterDateNoSend an email on this date. The date should be in ISO format
ignoreThrottledContactsBooleanNoWill return error if any of the contacts has been throttled
CURL --request  POST https://api.surveysparrow.com/v2/survey/78/shares/email/757
--header 'Authorization: Bearer <token>’\

--data '{
  "contacts": [{
     “email”:"john@example.com"
     }],
  "variables": {
    "team": "Engineering",
    "manager": "Jane Doe",
  },
  "sendLater": "2020-01-07T08:14:55+0000",
“ignoreThrottledContacts”:false   // will return error only if it is false and contacts throttled
}'

        
204 No content
                                    
SMS Share
PUT

https://api.surveysparrow.com/v1/survey/{surveyId}/shares/sms/{channelId}

Path Parameters
NameDescriptionType
surveyIdID of the surveynumber
shareIdID of the Sharenumber
Arguments for API Call
NameDescriptionTypeMandatory*
contactsNumbers of the contactArrayNo
contactListIds of the contactListArrayNo
messageText for the SMS ShareStringNo
smsTargetIdId of the SMS TargetNumberNo
variablesList of global variablesObjectNo
CURL --request  PUT https://api.surveysparrow.com/v1/survey/27/shares/sms/7878
--header 'Authorization: Bearer <token>’\
--header 'Content-Type: application/json' \
--- data {
contacts : [“+9199999999”,”+123232”,”+888328328”]
message:”Please take the survey”,
smsTargetId:90,
contactList:[9,23],
variables:{
uid:”Ab452baau”
}
}

                            
200 OK
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
}

                                    
View Targets
GET

http://api.surveysparrow.com/v1/targets

Options: Passed as Query Parameters
NameTypeRequired
maxResultsnumber min(1),max(200)No
pagenumberNo
CURL --request  GET  https://api.surveysparrow.com/v1/targets?maxResults=30&page=1
--header 'Authorization: Bearer <token>’\

        
{
targets: [ {
    id,
    name,
    description,
    icon,
    url,
    httpMethod,
    headers,
    properties,
    disabled
} ],
  page: currentPage,
  hasNextPage:boolean
}
        
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
                                    
NPS
Create NPS Survey
POST

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

Arguments for API Call
NameDescriptionTypeMandatory
surveyNameName of the surveyStringYes
email.bodyBody of emailStringNo
email.subjectSubject of emailStringNo
followUp.defaultDefault Follow up questionStringNo
followUp.advancedEnable Advanced Follow upBooleanNo
followUp.promotorsFollow up question for PromotersStringNo
followUp.passivesFollow up question for PassivesStringNo
followUp.detractorsFollow up question for DetractorsStringNo
thankYou.defaultDefault Thank you messageStringNo
thankYou.advancedEnable Thank you messageBooleanNo
thankYou.promotorsThank you message for PromotersStringNo
thankYou.passivesThank you message for PassivesStringNo
thankYou.detractorsThank you message for DetractorsStringNo
curl --request POST \
  --url 'https://api.surveysparrow.com/v1/nps' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
    "surveyName" : "nps_api",
    "email" : {
        "body": "hi",
        "subject": "this is test subject"
    },
    "followUp": {
        "default": "hello there"
    },
    "thankYou": {
        "advanced": true
    }
  }'
                                    
{
  "welcomeScreenYesButtonText": "builder.welcome_yes_proceed",
  "thankyou_json": [],
  "archived": false,
  "visibility": "Public",
  "published": true,
  "phishing": false,
  "id": 34512,
  "name": "nps_api",
  "surveyType": "NPS",
  "properties": {
    ...
  },
  "account_id": 17981,
  "user_id": 49900,
  "updated_at": "2020-01-31T06:17:25.783Z",
  "created_at": "2020-01-31T06:17:25.783Z",
  "euiVersion": 1,
  "templateName": null,
  "deleted_at": null,
  "survey_folder_id": null,
  "thankyou_template_id": null,
  "welcome_rtxt": null,
  "theme_id": null,
  "welcomeDescription": null
}

                                    
Share NPS Survey
POST

https://api.surveysparrow.com/v1/nps/{survey_id}/email

Path Parameters
NameDescription
survey_idID of the Survey
Arguments for API Call
NameDescriptionTypeMandatory
contactsContacts to send the NPSArray of emailsYes
contactListsList of contacts to send the NPSArray of contact list idsNo
modeMode of share (BLAST, DELAYED, SCHEDULE)StringNo, Default: BLAST
nameName of NPS shareStringYes
sendNowBlast EmailBooleanNo, Default: true
customPropertiesCustom PropertiesArrayNo
delayedDelayed Email ShareStringNo
scheduleSchedule Email ShareObjectNo
curl --request POST \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/email' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
    "contacts": [{"email":"johndoe@example.com"}],
    "name" : "NPS ",
    "mode" : "BLAST",
    }'
                                    
{
  "status": "ACTIVE",
  "properties": {},
  "id": 16632,
  "mode": "BLAST",
  "customProperties": {},
  "type": "EMAIL",
  "name": "NPS ",
  "survey_id": 34505,
  "account_id": 17981,
  "updated_at": "2020-01-31T06:16:01.229Z",
  "created_at": "2020-01-31T06:16:01.229Z",
  "deleted_at": null
}

                                    
View Responses
GET

https://api.surveysparrow.com/v1/nps/{survey_id}/responses

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
date.gteGreater than filter
date.lteLess than Filter

Date Format (MM/DD/YYYY)

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/responses?date.gte=12/01/2019' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'
                                    
[{
    "id": 3925,
    "feedback": "",
    "state": "COMPLETED",
    "score": 8,
    "properties": {},
    "customProperties": {},
    "tags": [],
    "sentiment": null,
    "contactProperties": {
        "id": 1500768,
        "firstName": "John",
        "lastName": "Doe",
        "email": "johndoe@example.com",
        "emailValidatedAt": "2020-01-31T06:04:55.470Z",
        "properties": {
            "emailValidation": {
                "email": "johndoe@example.com",
                "code": "4",
                "role": "false",
                "free_email": "false",
                "result": "Risky",
                "reason": "Accept All",
                "send_transactional": "1",
                "did_you_mean": ""
            }
        },
        "phone": null,
        "mobile": null,
        "jobTitle": null,
        "active": true,
        "unsubscribed": false,
        "unsubscribedToken": null,
        "sharedToken": "6e019aa5cd231da66ab1f8a87b420b19",
        "bounced": false,
        "spamVictim": false,
        "disposable": false,
        "profilePic": null,
        "attrs": {
            "email": "johndoe@gmail.com",
            "fullName": "John Doe",
            "firstName": "John",
            "lastName": "Doe"
        },
        "created_at": "2020-01-31T06:04:54.566Z",
        "updated_at": "2020-01-31T06:04:55.471Z",
        "deleted_at": null,
        "account_id": 17981
    },
    "responseEmailSent": false,
    "created_at": "2020-01-31T06:05:12.381Z",
    "updated_at": "2020-01-31T06:05:14.813Z",
    "deleted_at": null,
    "nps_channel_id": 16631,
    "nps_schedule_history_id": null,
    "account_id": 17981,
    "survey_id": 34505,
    "nps_trigger_id": 6296459,
    "contact_id": 1500768
}]
                                    
Get All Promoters
GET

https://api.surveysparrow.com/v1/nps/{survey_id}/responses/promoters

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
date.gteGreater than filter
date.lteLess than Filter

Date Format (MM/DD/YYYY)

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/responses/promoters?date.gte=12/01/2019' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'
                                    
[{
    "id": 3922,
    "feedback": "",
    "state": "COMPLETED",
    "score": 9,
    "properties": {},
    "customProperties": {},
    "tags": [],
    "sentiment": null,
    "contactProperties": {
      "id": 1500760,
      "firstName": "John",
      "lastName": "Doe",
      "email": "johndoe@example.com",
      "emailValidatedAt": "2020-01-31T05:05:45.401Z",
      "properties": {
        "emailValidation": {
          "email": "johndoe@example.com",
          "code": "4",
          "role": "false",
          "free_email": "false",
          "result": "Risky",
          "reason": "Accept All",
          "send_transactional": "1",
          "did_you_mean": ""
        }
      },
      "phone": null,
      "mobile": null,
      "jobTitle": null,
      "active": true,
      "unsubscribed": false,
      "unsubscribedToken": null,
      "sharedToken": "324c56a74f306d0d971409739ed4f1e7",
      "bounced": false,
      "spamVictim": false,
      "disposable": false,
      "profilePic": null,
      "attrs": {
        "email": "johndoe@example.com",
        "fullName": "John Doe",
        "firstName": "John",
        "lastName": "Doe
      },
      "created_at": "2020-01-31T05:05:44.513Z",
      "updated_at": "2020-01-31T05:05:45.402Z",
      "deleted_at": null,
      "account_id": 17981
    },
    "responseEmailSent": false,
    "created_at": "2020-01-31T05:35:34.302Z",
    "updated_at": "2020-01-31T05:35:39.739Z",
    "deleted_at": null,
    "nps_channel_id": 16624,
    "nps_schedule_history_id": null,
    "account_id": 17981,
    "survey_id": 34505,
    "nps_trigger_id": 6296453,
    "contact_id": 1500760
}]

                                    
Get All Passives
GET

https://api.surveysparrow.com/v1/nps/{survey_id}/responses/passives

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
date.gteGreater than filter
date.lteLess than Filter

Date Format (MM/DD/YYYY)

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/responses/passives?date.gte=12/01/2019' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'

                                    
[{
    "id": 3925,
    "feedback": "",
    "state": "COMPLETED",
    "score": 8,
    "properties": {},
    "customProperties": {},
    "tags": [],
    "sentiment": null,
    "contactProperties": {
        "id": 1500768,
        "firstName": "John",
        "lastName": Doe,
        "email": "johndoe@example.com",
        "emailValidatedAt": "2020-01-31T06:04:55.470Z",
        "properties": {
            "emailValidation": {
                "email": "johndoe@example.com",
                "code": "4",
                "role": "false",
                "free_email": "false",
                "result": "Risky",
                "reason": "Accept All",
                "send_transactional": "1",
                "did_you_mean": ""
            }
        },
        "phone": null,
        "mobile": null,
        "jobTitle": null,
        "active": true,
        "unsubscribed": false,
        "unsubscribedToken": null,
        "sharedToken": "6e019aa5cd231da66ab1f8a87b420b19",
        "bounced": false,
        "spamVictim": false,
        "disposable": false,
        "profilePic": null,
        "attrs": {
            "email": "johndoe@example.com",
            "fullName": "John Doe",
            "firstName": "John",
            "lastName": "Doe"
        },
        "created_at": "2020-01-31T06:04:54.566Z",
        "updated_at": "2020-01-31T06:04:55.471Z",
        "deleted_at": null,
        "account_id": 17981
    },
    "responseEmailSent": false,
    "created_at": "2020-01-31T06:05:12.381Z",
    "updated_at": "2020-01-31T06:05:14.813Z",
    "deleted_at": null,
    "nps_channel_id": 16631,
    "nps_schedule_history_id": null,
    "account_id": 17981,
    "survey_id": 34505,
    "nps_trigger_id": 6296459,
    "contact_id": 1500768
}]
                                    
Get All Detractors
GET

https://api.surveysparrow.com/v1/nps/{survey_id}/responses/detractors

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
date.gteGreater than filter
date.lteLess than Filter

Date Format (MM/DD/YYYY)

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/responses/detractors?date.gte=12/01/2019' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'

                                    
[{
    "id": 3923,
    "feedback": "",
    "state": "COMPLETED",
    "score": 5,
    "properties": {},
    "customProperties": {},
    "tags": [],
    "sentiment": null,
    "contactProperties": {
        "id": 1500763,
        "firstName": "John",
        "lastName": "Doe",
        "email": "johndoe@example.com",
        "emailValidatedAt": "2020-01-31T06:01:26.711Z",
        "properties": {
            "emailValidation": {
                "email": "johndoe@example.com",
                "code": "4",
                "role": "false",
                "free_email": "false",
                "result": "Risky",
                "reason": "Accept All",
                "send_transactional": "1",
                "did_you_mean": ""
            }
        },
        "phone": null,
        "mobile": null,
        "jobTitle": null,
        "active": true,
        "unsubscribed": false,
        "unsubscribedToken": null,
        "sharedToken": "7655aa2b17a5aaac9628057b7e63ef3c",
        "bounced": false,
        "spamVictim": false,
        "disposable": false,
        "profilePic": null,
        "attrs": {
            "email": "johndoe@example.com",
            "fullName": "John Doe",
            "firstName": "John",
            "lastName": "Doe"
        },
        "created_at": "2020-01-31T06:01:02.318Z",
        "updated_at": "2020-01-31T06:01:26.712Z",
        "deleted_at": null,
        "account_id": 17981
    },
    "responseEmailSent": false,
    "created_at": "2020-01-31T06:01:58.295Z",
    "updated_at": "2020-01-31T06:02:01.637Z",
    "deleted_at": null,
    "nps_channel_id": 16629,
    "nps_schedule_history_id": null,
    "account_id": 17981,
    "survey_id": 34505,
    "nps_trigger_id": 6296457,
    "contact_id": 1500763
}]
                                    
Get Metrics
GET

https://api.surveysparrow.com/v1/nps/{survey_id}/metrics

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
date.gteGreater than filter
date.lteLess than Filter

Date Format (MM/DD/YYYY)

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/metrics' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'
                                    
{
  "nps": 0,
  "detractors": 1,
  "passives": 2,
  "promoters": 1,
  "total": 4
}
                                    
Get Trend Data
GET

https://api.surveysparrow.com/v1/nps/{survey_id}/trend

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
date.gteGreater than filter
date.lteLess than Filter

Date Format (MM/DD/YYYY)

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/trend?date.gte=12/01/2019' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'

                                    
[
  {
    "timestamp": "1/31/2020",
    "nps": 0,
    "responses": 4,
    "promoters": 1,
    "passives": 2,
    "detractors": 1
  }
]
                                    
Get Metrics
GET

https://api.surveysparrow.com/v1/survey/{surveyId}/invite

Path Parameters
NameDescription
survey_idID of the Survey
Options: Passed as Query Parameters
NameDescription
date.gteGreater than filter
date.lteLess than Filter

Date Format (MM/DD/YYYY)

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/metrics' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>'
                                    
{
  "nps": 0,
  "detractors": 1,
  "passives": 2,
  "promoters": 1,
  "total": 4
}
                                    
View Shares
GET

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

Path Parameters
NameTypeDescription
surveyIdnumberID of the survey
Options: Passed as Query Parameters
NameTypeRequired
maxResultsnumber min(1),max(200)No
pagenumberNo
CURL --request  GET  https://api.surveysparrow.com/v1/nps/78/shares
--header 'Authorization: Bearer <token>’

        
{
   "shares": [
       {
           "id": 6,
           "type": "LINK",
           "mode": "LINK",
           "name": "Web Link Share",
           "status": "ACTIVE",
           "properties": {
               "acceptAnonymousResponse": false
           },
           "customProperties": {}
       },
       {
           "id": 8,
           "type": "LINK",
           "mode": "LINK",
           "name": "Web Link Share 2",
           "status": "ACTIVE",
           "properties": {
               "acceptAnonymousResponse": true
           },
           "customProperties": {}
       },
       {
           "id": 9,
           "type": "EMAIL",
           "mode": "BLAST",
           "name": "Email Share 1",
           "status": "ACTIVE",
           "properties": {
               "email": {
                   "body": "",
                   "subject": "Your feedback matters! Help us serve you better.",
                   "replyEmail": "nikhil@surveysparrow.com"
               }
           },
           "customProperties": {}
       }
     ]
"hasNextPage": false
}

        
View Share
GET

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

Path Parameters
NameTypeDescription
surveyIdnumberID of the survey
ShareIdnumberID of the share (channel)
CURL --request  GET  https://api.surveysparrow.com/v1/nps/78/shares/890
--header 'Authorization: Bearer <token>’
        
{
   "id": 890,
   "type": "MOBILE_SDK",
   "mode": "MOBILE_SDK",
   "name": "Mobile SDK share 1",
   "status": "ACTIVE",
   "properties": {},
   "customProperties": {},
   "token": "ntt-2f3fb7"
}

        
EMP360
Create Invite
POST

https://api.surveysparrow.com/v1/survey/{surveyId}/invite

Path Parameters
NameDescription
surveyIdID of the Survey
Body
NameDescription
Subject (required){ fullName:- name of subject
email:- email of subject }
Evaluators (required){ fullName:- name of evaluator
email:- email of evaluator
relation:- relation of evaluator with subject (case-sensitive)
}
Approver (required){ fullName:- name of subject
email:- email of subject }
Properties (required){ requireApproval: evaluators need approval of approver,
selfEvaluation: Subject can self evaluate,
selfNomination: subject can choose his evaluators }
curl --request POST 'https://api.surveysparrow.com/v1/survey/{surveyId}/invite'
--header 'Authorization: Bearer <token>’\
--header 'Content-Type: application/json' \
--data '{
	subject:{
	fullName: “Jon”,
	email:”email@jon.com”
	},
	evaluators:[
	{
fullName: “JonI”,
	email:”email@jonI.com”,
	relation:”peer”
}
],
approver:{
fullName: “Jone”,
	email:”email@jone.com”
},
properties:{
selfEvaluation:true,
requireApproval:true,
selfNomination:true
}
}


                                    
{ Status: 200 }
                                    
Update Invite
PUT

https://api.surveysparrow.com/v1/survey/{surveyId}/subject/{subjectId}/invite

Path Parameters
NameDescription
surveyIdID of the Survey
subjectIdID of the subject
Body
NameDescription
Evaluators (required){ fullName:- name of evaluator
email:- email of evaluator
relation:- relation of evaluator with subject }
curl --request PUT 'https://api.surveysparrow.com/v1/survey/{surveyId}/subject/{subjectId}/invite'

--header 'Authorization: Bearer <token>’\
--header 'Content-Type: application/json' \
--data {
evaluators:[
{
fullName: “JonI”,
	email:”email@jonI.com”,
	relation:”peer”
}
    ]
}



                                    
{ Status: 200 }
                                    
Get Survey Approvers
GET

https://api.surveysparrow.com/v1/survey/{surveyId}/approvers?pageNo=1&pageLimit=50

Path Parameters
NameDescription
surveyIdID of the Survey
Body
NameDescription
pageNoPage no of the results user want to retrieve (starts from 1)
pageLimitNo. of records per page (max:- 500,min:-1)
curl --request GET 'https://api.surveysparrow.com/v1/survey/{surveyId}/approvers?pageNo=1&pageLimit=50' \
--header 'Authorization: Bearer <token>’\




                                    
count :- total no.of records (NUMBER),
pageLimit:- limit of records per page (NUMBER),
pageNo :- current pageNo (NUMBER),
list: [  // array of objects
    {
        name: name of approver (STRING),
        email:- approver email (EMAIL)l,
        joinedPortal :- whether he signedUp for portal or not (BOOLEAN),
        approvals :- total number of of approval requests (NUMBER),
        approved :- total number of approved requests (NUMBER),
        declined :- total number of rejected requests (NUMBER),
        pending :- total number of pending requests (NUMBER),
        id :- approver id (NUMBER)
    }
    ]
}

                                    
Get Subject Evaluators
GET

https://api.surveysparrow.com/v1/survey/{surveyId}/subject/{subjectId}/evaluators?pageNo=1&pageLimit=50

Path Parameters
NameDescription
surveyIdID of the Survey
subjectIdID of the subject
Body
NameDescription
pageNoPage no of the results user want to retrieve (starts from 1)
pageLimitNo. of records per page (max:- 500,min:-1)
curl --request GET 'https://api.surveysparrow.com/v1/survey/{surveyId}/subject/{subjectId}/evaluators?pageNo=1&pageLimit=50' \
--header 'Authorization: Bearer <token>’\





                                    
count :- total no.of records (NUMBER),
pageLimit:- limit of records per page (NUMBER),
pageNo :- current pageNo (NUMBER),
list: [  // array of objects
    {
        name: name of evaluator (STRING),
        email:- evaluator email (EMAIL)l,
        joinedPortal :- whether he signedUp for portal or not (BOOLEAN),
        id :- evaluator id (NUMBER),
        status :- approval Status ( ENUM (pending,approved,rejected) )
    }
  ]
}



                                    
Get Subjects
GET

https://api.surveysparrow.com/v1/survey/{surveyId}/subjects?pageNo=1&pageLimit=50

Path Parameters
NameDescription
surveyIdID of the Survey
subjectIdID of the subject
Body
NameDescription
pageNoPage no of the results user want to retrieve (starts from 1)
pageLimitNo. of records per page (max:- 500,min:-1)
curl --request GET 'https://api.surveysparrow.com/v1/survey/{surveyId}/subjects?pageNo=1&pageLimit=50' \
--header 'Authorization: Bearer <token>’\






                                    
{
    count :- total no.of records (NUMBER),
    pageLimit:- limit of records per page (NUMBER),
    pageNo :- current pageNo (NUMBER),
    list: [  // array of objects
        {
            name: name of subject (STRING),
            email:- subject email (EMAIL)l,
            joinedPortal :- whether he signedUp for portal or not (BOOLEAN),
            id :- evaluator id (NUMBER),
            approver:{
                id: approver Id of subject (NUMBER),
                name: name of approver (STRING),
                email:- approver email (EMAIL)l,
                joinedPortal :- whether he signedUp for portal or not (BOOLEAN),
            },
            properties:{
                selfEvaluation :- subject can evaluate himself (BOOLEAN),
                selfNomination :- subject can nominate his evaluators (BOOLEAN),
                requireApproval :- subject nominated evaluators need approval (BOOLEAN)
            }
        }
    ]
}