SurveySparrow Developer Portal

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.

Login to your surveysparrow account and go to Settings → Apps & Integrations
Create a Private App
Enter Name, Description, select scope and generate the access token
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)
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.

Scope	Permission
View Contacts	List Contacts
Manage Contacts	Create Contacts, Update Contacts
View Contact Lists	List Contact Lists
Manage Contact List	Create Contact List, Update Contact List
View Survey	List Surveys
View Responses	List Responses
Manage Share Survey	Update 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 Code	Permission
200 OK	Request is successful
202 Accepted	Request accepted but it is queued or processing
400 Bad Request	Request has missing required parameters or validation errors
401 Unauthorized	Bad Token or missing token
403 Forbidden	Access denied for the requested resource
404 Not Found	The requested resource doesn’t exist
409 Conflict	Request conflicts with another, trying to create already existing resource
429 Too Many Requests	Api request limit exceeded
500 Internal Server Error	Something went wrong in Surveysparrow
204 No Content	Request has succeeded

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

Error Type	Description
missing_scope	Token doesn’t has the requested resource scope
backend_error	Error in Surveysparrow servers
already_exist	The resource trying to create already exist
permission_denied	You don’t have the access rights for requested resource
not_found	The requested resource is not available in the system.
not_active	Resource is not active now, so you can’t perform the operation
limit_exceeded	You have reached your hourly quota.
disabled	The app or integration is disabled by the creator.
bad_token	Due 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
Name	Description
maxResults	No of results needed in a request
page	Page 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
Name	Description	Type	Mandatory
email	Email of the contact	string	Yes
name	Name of the contact	string	No
phone	Phone number of the contact	string	No
mobile	Mobile number of the contact	string	No
jobTitle	Job Title of the contact	string	No

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
Name	Description	Type
id	ID of the Contact	integer
email	Email of the contact	string
name	Name of the Contact	string
phone	Phone No: of the Contact	string
mobile	Mobile No: of the Contact	string
jobTitle	Job Title of the Contact	string
active	Status of contact is active or not	boolean
unsubscribed	Status of the contact is unsubscribed or not	boolean

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
Name	Description
contact_list_id	ID of the contact list

Response Attribute
Status	Description
created	Contacts Created
pending	Pending 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
Name	Description
contact_list_id	ID of the Contact List

Response Attributes
Name	Description	Type
id	ID of the Contact	integer
email	Email of the contact	string
name	Name of the Contact	string
phone	Phone No: of the Contact	string
mobile	Mobile No: of the Contact	string
jobTitle	Job Title of the Contact	string
active	Status of contact is active or not	boolean
unsubscribed	Status of the contact is unsubscribed or not	boolean

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"
}]
                                    

Get All Contact Lists

GET

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

CURL --request  GET https://api.surveysparrow.com/v1/contactlist
--header 'Authorization: Bearer <token>’\

[
   {
       "id": 3,
       "name": "2",
       "description": "Auto created during the contact import (2)"
   },
   {
       "id": 4,
       "name": "3",
       "description": "Auto created during the contact import (3)"
   },
   {
       "id": 12,
       "name": "a",
       "description": "Auto created during the contact import (a)"
   }
]

                                    

Get All Contacts Of a List

GET

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

Path Parameters
Name	Type	Description
id	number	ID of the contact list

CURL --request  GET https://api.surveysparrow.com/v1/contactlist/12/contacts
--header 'Authorization: Bearer <token>’\

{
   "contacts": [
       {
           "id": 53346,
           "email": "test@test.com",
           "mobile": null,
           "jobTitle": null,
           "active": true,
           "unsubscribed": false,
           "name": "test "
       },
       {
           "id": 53291,
           "email": "test@test.com",
           "mobile": null,
           "jobTitle": null,
           "active": true,
           "unsubscribed": false,
           "name": "test"
       }],
   "hasNextPage": false
}


                                    

Create a Contact List

POST

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

Arguments for API Call
Name	Type	Description
name	string	Name of the Contact List
description	string	Description of the Contact List

CURL --request  POST https://api.surveysparrow.com/v1/contactlist
--header 'Authorization: Bearer <token>’\
--header 'Content-Type: application/json' \
-- payload {
   "name":"Contact List Name",
   "description":"description"
      }


                                    

Response Status :- 200
Data :- {
   "id": 26,
   "name": "Contact List Name"
}

                                    

Delete a Contact List

GET

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

Arguments for API Call
Name	Type	Description
id	number	ID of the contact list

CURL --request  DELETE https://api.surveysparrow.com/v1/contactlist/12
--header 'Authorization: Bearer <token>’\
                                    

Response Status :- 200

Workspace

View Workspaces

GET

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

Options: Passed as Query Parameters
Name	Description
maxResults	No of results needed in a request
page	Page 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
Name	Description
id	ID 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
Name	Description
maxResults	No of results needed in a request
page	Page 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
Name	Description
id	ID 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
Name	Description
survey_id	ID of the survey

Options: Passed as Query Parameters
Name	Description
maxResults	No of results needed in a request
page	Page No

Response Attributes
Name	Description	Type
submissions	Submissions of the survey	Array
answers	Answers of a submission	Array
questions	Questions of the survey	Array

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,
            "question_tags": [
              {
                "name": "dropdown",
                "id": 13
              }
            ]
          },
          {
            "answer": [
              "Visual Studio Code",
              "Atom",
              "Vim"
            ],
            "detailedAnswer": [
              {
                "choiceId": 50,
                "choiceText": "Visual Studio Code"
              },
              {
                "choiceId": 51,
                "choiceText": "Atom"
              },
              {
                "choiceId": 52,
                "choiceText": "Vim"
              }
            ],
            "question": " Select your favourite editor/s ? ",
            "question_tags": [],
            "question_id": 44,
          },
        ]
      },
    ],
    "hasNextPage": false,
    "questions": [
      {
        "question": " How much you like this editor",
        "id": 43
      },
      {
        "question": " Select your favourite editor/s ? ",
        "id": 44
      },
    ]
  }
}

                                    

View Submission

GET

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

Path Parameters
Name	Description
survey_id	ID of the Survey
id	ID 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,
      "question_tags": [
        {
          "name": "dropdown",
          "id": 13
        }
      ]
    },
    {
      "answer": "jane.doe@gmail.com",
      "question": " Please share your Email",
      "question_id": 2433,
      "question_tags": []
    },
    {
      "answer": 9,
      "question": "Please rate us on a scale of 1-10",
      "question_id": 2434,
      "question_tags": []
    },
    {
      "answer": "Netflix",
      "detailedAnswer": [
        {
          "choiceId": 56,
          "choiceText": "Netflix"
        }
      ],
      "position": 3,
      "question": " Which are the streaming service you are used/using",
      "question_id": 2435,
      "question_tags": [],
    }
  ]
}

                                    

Delete Submission

DELETE

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

Path Parameters
Name	Description
survey_id	ID of the Survey
id	ID of the Submission

CURL --request  DELETE  https://api.surveysparrow.com/v1/surveys/216/submissions/4983
--header 'Authorization: Bearer <token>'\
                                    

Status 204

View Questions

GET

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

Path Parameters
Name	Description
id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
maxResults	No of results needed in a request
page	Page No
tagName	Name of the tag

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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
maxResults	No of results needed in a request
page	Page 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
Name	Description	Required
survey_id	Id of the survey	Yes

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
Name	Description	Required	DataType	Default Value
survey_id	Id of the survey	Yes	Number

Other Arguments
Name	Description	Required	DataType	Default Value
partialSubmission	Allow partial submission to the survey	No	Boolean	True
editResponse	Allow user to edit and resubmit the survey	No	Boolean	False

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
Name	Description	Required	DataType	Default Value	Allowed values
name	Name of the survey	Yes	String
surveyType	Type of the survey	Yes	String		ClassicForm
workspace_id	Id of the workspace	No	Number	Workspace “General” will be taken
theme_id	Name of the template	No	Number	Null
welcomeScreenYesButtonText	Welcome screen button label	No	String	Sure, ask.
welcomeDescriptionEnabled	It will enable welcome screen description	No	Boolean	False
welcomeText	Add a welcome page to the survey. Welcome screen title	No	String
welcomeDescription	Welcome screen description	No	String
thankyou_json	Add a thank you page to the survey	No	Array

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
Name	Description	Required	DataType	Default Value
survey_id	Id of the survey	Yes	Number

Other Arguments
Name	Description	Required	DataType	Default Value
name	Section heading or title	Yes	String
description	Section description	No	Object
properties	Pass the extra information about a section, like section button label	No	Object Ex: `"properties": { "label": "ccc" }`	label: “Continue”
questions	It will add questions to this section	No	Array

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
Name	Description	Required	DataType	Allowed values
section_id	Id of the section	Yes	Number

Other Arguments
Name	Description	Required	DataType	Allowed values
text	Question text	Yes	String
type	Type of the question	Yes	String	FileInput Or TextInput Or OpinionScale
description	Question description	No	String
required	If it is mandatory question or not	No	Boolean	True
properties	Extra information can be passed in this	No	Object 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
Name	Description	Required	DataType
survey_id	Id of the survey	Yes	Number
section_id	Id of the section	Yes	Number

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
Name	Description	Required	DataType
survey_id	Id of the survey	Yes	Number
question_id	Id of the question	Yes	Number

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
Name	Description	Required	DataType	Allowed Values
surveyType	Type of the survey	Yes	String	Conversational 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>'

                                

View Survey Integrations

GET

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

Path Parameters
Name	Description	DataType
surveyId	ID of the survey	number

CURL --request  GET \
--url 'https://api.surveysparrow.com/v1/survey/12/integrations' \
--header 'Authorization: Bearer <token>’\

--- data   {
    "list": [
        {
            "id": 1111,
            "active": false,
            "properties": {},
            "name": "Monday",
            "description": "Create a task/Lead in Monday using Survey Responses"
        },
        {
            "id": 1108,
            "active": false,
            "properties": {
                "label": "test-standup-public",
                "value": "C0120MCU0TY",
                "allQuestions": true,
                "questionIds": [
                    1730,
                    1731,
                    1732,
                    1843
                ]
            },
            "name": "Slack",
            "description": "Send survey responses via Slack and notify channels/users about new survey submissions."
        },
        {
            "id": 1100,
            "active": false,
            "properties": {},
            "name": "Aweber",
            "description": "Manage your Aweber subscribers and collect and manage leads."
        },
        {
            "id": 1101,
            "active": false,
            "properties": {},
            "name": "Salesforce",
            "description": "Understand feedback of your customers in Salesforce out of the box"
        },
        {
            "id": 1103,
            "active": false,
            "properties": {},
            "name": "Googlesheets",
            "description": "Sync your survey responses with Google Sheets. Receive real-time survey data seamlessly."
        },
        {
            "id": 1102,
            "active": false,
            "properties": {},
            "name": "Hubspot",
            "description": "Capture new leads, map survey data and incorporate feedback surveys into marketing campaigns."
        },
        {
            "id": 1104,
            "active": false,
            "properties": {},
            "name": "SurveySparrowAudience",
            "description": "Create or Update contacts in SurveySparrow"
        },
        {
            "id": 1105,
            "active": false,
            "properties": {},
            "name": "Intercom",
            "description": "Deliver better customer experience with Intercom integration"
        },
        {
            "id": 1106,
            "active": false,
            "properties": {},
            "name": "Mailchimp",
            "description": "Manage your Mailchimp subscribers and collect and manage leads."
        },
        {
            "id": 1107,
            "active": false,
            "properties": {},
            "name": "FacebookPixel",
            "description": "Track and assess the effectiveness of your survey campaigns with Facebook Pixel integration."
        },
        {
            "id": 1109,
            "active": false,
            "properties": {},
            "name": "GoogleAnalytics",
            "description": "View and analyze survey traffic with Google Analytics"
        },
        {
            "id": 1110,
            "active": false,
            "properties": {},
            "name": "Teams",
            "description": "SurveySparrow integration with Teams lets you create engaging surveys and share responses via chats."
        }
    ]
}


                                

Important hint

Supported question types: [FileInput,TextInput,OpinionScale]
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:

Key	Description	DataType	Default Value	Required	Allowed values
min	Opinion scale min label	String	Least Likely	No
max	Opinion Scale max label	String	Most Likely	No
start	Start value of the opinion scale	Number	0	No	0 or 1
step	Opinion scale step length	Number	10	No	3 to 10

2. TextInput:

Key can pass inside the properties.data:

Key	Description	DataType	Default Value	Required	Allowed values
type	Type of the textinput	String	SINGLE_LINE	No	SINGLE_LINE Or MULTI_LINE

3. FileInput:

Key can pass inside the properties.data:

Key	Description	DataType	Default Value	Required	Allowed values
fileTypes	Type of the file allowed to upload	Array	["image", "doc"]	No	["image", "doc", "video"]

Custom Property (Variables)

Get all Custom Property of the survey

GET

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

Path Parameters
Name	Description	Required	DataType
survey_id	ID of the Survey	Yes	Number

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
Name	Description	Required	DataType	Allowed Values
survey_id	Id of the survey	Yes	Number

Other Arguments
Name	Description	Required	DataType	Allowed Values
label	Custom property label	Yes	String
name	Name of the custom property Used to pass values to a value to the variable (API Identifier)	Yes	String
description	Small note about the variable	No	String
type	The data type of the variable	Yes	String	STRING 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
Name	Description	Required	DataType
survey_id	Id of the survey	Yes	Number
variable_id	Id of the custom property	Yes	Number

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

                                


{ "success": true }

Clone a Survey

POST

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

Path Parameters
Name	Datatype	Required	Description
id	integer	Yes	ID of the Survey

Other Arguments
Name	Datatype	Required	Default value	Description
surveyType	string	No	It gets cloned as the same type as parent	Survey type to which the survey should be cloned

surveyType:

Classic, Chat can be cloned to any of these types only.
Offline cannot be cloned to any other type and vice versa.
NPS can be cloned to NPSChat and vice versa.

Types: Conversational, ClassicForm, OfflineApp, NPS, NPSChat

curl  --request POST \
--url 'https://api.surveysparrow.com/v1/surveys/12/clone' \
--header 'Content-Type: application/json'
--header 'Authorization: Bearer <token>’
   --data {
       "surveyType": 'ClassicForm'
   }

                

{
   "id": 27,
   "name": "My survey - Clone",
   "welcome_rtxt": null,
   "welcomeDescription": null,
   "welcomeScreenYesButtonText": "builder.welcome_yes_proceed",
   "thankyou_json": [],
   "archived": false,
   "visibility": "Mine",
   "surveyType": "ClassicForm",
   "templateName": null,
   "properties": {
       "autosizeHeading": true,
       "surveyRandomiser": false,
       "progress": {
           "builderCompleted": true,
           "designCompleted": true,
           "shareCompleted": true,
           "integrationCompleted": true
       }
   },
   "published": true,
   "euiVersion": 2,
   "phishing": false,
   "primaryLanguage": "en",
   "multiLanguageWelcomeRtxt": null,
   "multiLanguageWelcomeDescription": null,
   "multiLanguageWelcomeScreenYesButtonText": null,
   "multiLanguageThankyouJson": null,
   "multiLanguageName": null,
   "created_at": "2021-03-24T05:49:27.305Z",
   "updated_at": "2021-03-24T05:49:27.761Z",
   "deleted_at": null,
   "account_id": 2,
   "user_id": 2,
   "survey_folder_id": 1,
   "thankyou_template_id": null,
   "theme_id": null
}
                

Get Reports public link for a given Survey

GET

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

Path Parameters
Name	Datatype	Required	Description
survey_id	integer	Yes	ID of the survey

Query Parameters
Name	Datatype	Required	Description
report_id	integer	No	ID of the report. If value is not passed, then the default report id will be taken.

curl --location --request GET
'https://api.surveysparrow.com/v1/surveys/12/report/link?report_id=10' \
--header 'Authorization: Bearer <Token>'
                

https://sample.surveysparrow.com/public/reports/survey/12/o6WrLpCI

Get unique Survey link for each contact

POST

https://api.surveysparrow.com/v1/survey/{survey_id}/channels/{channel_id}/contacts/survey-link

Path Parameters
Name	Datatype	Required	Description
survey_id	int	Yes	ID of the survey
channel_id	int	Yes	ID of the email channel

Other Arguments
Name	Datatype	Required	Description
contactIds	Array of ids	No	Array of contact ids
contactListIds	Array of ids	No	Array of contact list ids

Restrictions:

Either contactIds or contactListIds should be given.
Upto 100 contact Ids can be given inside the array.
Upto 100 contact Ids can be given inside the array.
NPS, NPS-Chat survey links are not supported.

curl --location --request POST
'https://api.surveysparrow.com/v1/survey/12/channels/5/contacts/survey-link' \
--header 'Authorization: Bearer <Token>'
   --data {
       "contactIds": [1014, 1013],
       "contactListIds": [1]
   }

                

[
   {
       "1014": "http://bing.surveysparrow.test/s/new-survey234/tgC-ed21690a6a52baee"
   },
   {
       "1013": "http://bing.surveysparrow.test/s/new-survey234/tgC-7b2e25366c182c5f"
   },
   {
       "1012": "http://bing.surveysparrow.test/s/new-survey234/tgC-ed93c41a19f8e08d"
   }
]

                

Create Link

POST

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

Path Parameters
Name	Description
survey_id	ID 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
Name	Description
share_id	ID of the share

Arguments for API Call
Name	Description	Type	Mandatory*
contacts	Email of the Contact	Array	No
lists	Name of the Contact List	Array	No
customParams	Custom Variables for the Survey	Object	No
sendLaterInDays	Send an email after a certain number of days.	Number	No
sendLater	Send an email on this date. The date should be in ISO format.	Date	No

*Atleast one of the Arguments must be specified

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
Name	Type	Description
surveyId	number	ID of the survey
ShareId	number	ID of the share (channel)

Arguments for API Call
Name	Type	Mandatory	Description
contacts	Array Of emails	No	List of contacts to send the Survey
lists	Array Of ContactList names	No	Array of contactList to send the Survey
variables	Object	No	Variables for the Survey
sendLaterInDays	Number	No	sendLaterInDays
sendLater	Date	No	Send an email on this date. The date should be in ISO format
ignoreThrottledContacts	Boolean	No	Will return error if any of the contacts has been throttled

CURL --request  PUT 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
Name	Description	Type
surveyId	ID of the survey	number
shareId	ID of the Share	number

Arguments for API Call
Name	Description	Type	Mandatory*
contacts	Numbers of the contact	Array	No
contactList	Ids of the contactList	Array	No
message	Text for the SMS Share	String	No
smsTargetId	Id of the SMS Target	Number	No
variables	List of global variables	Object	No

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

SMS Share (v2)

PUT

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

Path Parameters
Name	Type	Description
surveyId	number	ID of the survey
shareId	number	ID of the share (channel)

Arguments for API Call
Name	Type	Mandatory	Description
contacts	Array Of mobile numbers	No	List of contacts to send the Survey
lists	Array Of ContactList ids	No	List of contacts to send the Survey
variables	Object	No	Variables for the Survey
message	text	No	Text for the SMS Share
smsTargetId	Number	No	Id of the SMS Target

CURL --request  PUT https://api.surveysparrow.com/v2/survey/78/shares/sms/757
--header 'Authorization: Bearer <token>’\

--data '{
  "contacts": [{
     “mobile”:"+91222222",
    "variables": {
    "id": "ERC"
  },
     }],
  "variables": {
    "team": "Engineering",
    "manager": "Jane Doe",
  }
“message”:”Please take the survey”
}'

                            

200 OK

View Shares

GET

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

Path Parameters
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
maxResults	No of results needed in a request
page	Page 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
Name	Type	Required
maxResults	number min(1),max(200)	No
page	number	No

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
Name	Description
maxResults	No of results needed in a request
page	Page 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
Name	Description	Type	Mandatory
name	Name of the Webhook	String	No
url	URL of the Webhook	String	Yes
surveyId	Survey ID of Survey for the Webhook	Integer	Yes
httpMethod	Request Type	String	Yes
headers	Headers of the Request	Array	Yes
payload	Payload of the Webhook	Object	No

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
Name	Description
id	ID of the Webhook

Arguments for API Call
Name	Description	Type	Mandatory
name	Name of the Webhook	String	No
url	URL of the Webhook	String	No
httpMethod	Request Type	String	No
headers	Headers of the Request	Array	No
payload	Payload of the Webhook	Object	No

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
Name	Description
id	ID 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
Name	Description	Type	Mandatory
surveyName	Name of the survey	String	Yes
email.body	Body of email	String	No
email.subject	Subject of email	String	No
followUp.default	Default Follow up question	String	No
followUp.advanced	Enable Advanced Follow up	Boolean	No
followUp.promotors	Follow up question for Promoters	String	No
followUp.passives	Follow up question for Passives	String	No
followUp.detractors	Follow up question for Detractors	String	No
thankYou.default	Default Thank you message	String	No
thankYou.advanced	Enable Thank you message	Boolean	No
thankYou.promotors	Thank you message for Promoters	String	No
thankYou.passives	Thank you message for Passives	String	No
thankYou.detractors	Thank you message for Detractors	String	No

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
Name	Description
survey_id	ID of the Survey

Arguments for API Call
Name	Description	Type	Mandatory
contacts	Contacts to send the NPS	Array of emails	Yes
contactLists	List of contacts to send the NPS	Array of contact list ids	No
mode	Mode of share (BLAST, DELAYED, SCHEDULE)	String	No, Default: BLAST
name	Name of NPS share	String	Yes
sendNow	Blast Email	Boolean	No, Default: true
customProperties	Custom Properties	Array	No
delayed	Delayed Email Share	String	No
schedule	Schedule Email Share	Object	No

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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
date.gte	Greater than filter
date.lte	Less 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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
date.gte	Greater than filter
date.lte	Less 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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
date.gte	Greater than filter
date.lte	Less 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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
date.gte	Greater than filter
date.lte	Less 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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
date.gte	Greater than filter
date.lte	Less 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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
date.gte	Greater than filter
date.lte	Less 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
Name	Description
survey_id	ID of the Survey

Options: Passed as Query Parameters
Name	Description
date.gte	Greater than filter
date.lte	Less 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
Name	Type	Description
surveyId	number	ID of the survey

Options: Passed as Query Parameters
Name	Type	Required
maxResults	number min(1),max(200)	No
page	number	No

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": "johndoe@surveysparrow.com"
               }
           },
           "customProperties": {}
       }
     ]
"hasNextPage": false
}

        

View Share

GET

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

Path Parameters
Name	Type	Description
surveyId	number	ID of the survey
ShareId	number	ID 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"
}

        

Get Email Trigger Information

GET

https://api.surveysparrow.com/v1/nps/{survey_id}/shares/{channel_id}/triggers

Query Parameters
Name	Type	Required	Description
page	number	No	Page no
maxResults	number min(1),max(100)	No	Max number of results
opened	Boolean	No	Email Opened
blocked	Boolean	No	Email Blocked
throttled	Boolean	No	Email Throttled

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/shares/{channel_id}/triggers?maxResults=50' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <Token>'

        

{
  "id": 710,
  "type": "EMAIL",
  "mode": "BLAST",
  "name": "NPS ",
  "status": "ACTIVE",
  "properties": {
    "email": {
      "body": "",
      "subject": "Your feedback matters! Help us serve you better.",
      "replyEmail": "johndoe@example.com"
    }
  },
  "customProperties": {},
  "npsEmailStatus": [
    {
      "id": 679,
      "throttled": false,
      "throttledRuleType": null,
      "opened": true,
      "blocked": false,
      "blockedReason": null,
      "contact": {
        "id": 1094,
        "firstName": "john",
        "lastName": doe,
        "email": "johndoe@example.com"
      }
    }
  ]
}


        

Create NPS SMS Share

POST

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

Path Parameters
Name	Description
survey_id	ID of the Survey

Arguments for API Call
Name	Description	Type	Mandatory
contacts	Contacts to send the NPS	Array of mobile numbers	Yes
contactLists	List of contacts to send the NPS	Array of contact list ids	No
mode	Mode of share (BLAST, DELAYED, SCHEDULE)	String	No, Default: BLAST
name	Name of NPS share	String	Yes
sendNow	Blast SMS Share	Boolean	No, Default: true
customProperties	Custom Properties	Array	No
delayed	Delayed SMS Share	String	No
schedule	Schedule SMS Share	Object	No
properties	SMS Content	Object	No

curl --request POST \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/sms \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
  "contacts": [
    {
      "mobile": "+xxxxxxx"
    }
  ],
  "name": "SMS API Share 1",
  "properties": {
    "content": "Take survey via sms",
    "smsTargetId": 1
  },
  "sendNow": true,
  "variables": {
    "name": "user-name"
  }
}'

                                

{
   "status": "ACTIVE",
   "default": false,
   "id": 5,
   "survey_id": 2,
   "account_id": 2,
   "mode": "BLAST",
   "properties": {
       "sms": {
           "content": "Take survey via sms",
           "target_id": 1
       }
   },
   "customProperties": {
       "name": "user-name"
   },
   "type": "SMS",
   "name": "SMS API Share 1",
   "updated_at": "2021-04-09T11:49:14.268Z",
   "created_at": "2021-04-09T11:49:14.268Z",
   "deleted_at": null
}

                                

Create NPS Share Reminder

POST

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

Path Parameters
Name	Description
survey_id	ID of the Survey
share_id	ID of the NPS channel

Arguments for API Call
Name	Description	Type	Mandatory
body	Email / SMS body	String	No
subject	Subject for Email reminder	String	No
type	Reminder type	String	Yes, Options: NOT_RESPONDED/PARTIALLY_RESPONDED
frequency	Schedule frequency	String	Yes, Options: Days/Weeks/Months/Years
interval	Number in which frequency applies. Eg: 1 Week.	string	Yes, Default: true

curl --request POST \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/shares/{share_id}/reminders \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
type:NOT_RESPONDED
frequency:Days
interval:50
}'

                                

{
   "sent_count": 0,
   "id": 2,
   "afterDays": 50,
   "type": "NOT_RESPONDED",
   "custom_interval": "50",
   "frequency": "Days",
   "survey_id": 2,
   "nps_channel_id": 5,
   "account_id": 2,
   "subject": null,
   "body": null,
   "updated_at": "2021-04-09T12:16:13.825Z",
   "created_at": "2021-04-09T12:16:13.825Z",
   "deleted_at": null
}

                                

Delete NPS Reminder

DELETE

https://api.surveysparrow.com/v1/nps/{survey_id}/shares/{share_id}/reminders/{reminder_id}

Path Parameters
Name	Description
survey_id	ID of the Survey
share_id	ID of the NPS channel
reminder_id	ID of the reminder

curl --request DELETE \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/shares/{share_id}/reminders/{reminder_id} \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \

                                

{"success": true}

List all NPS Reminders

GET

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

Path Parameters
Name	Description
survey_id	ID of the Survey
share_id	ID of the NPS channel
reminder_id	ID of the reminder

curl --request GET \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/shares/{share_id}/reminders/ \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \

[
   {
       "id": 95,
       "afterDays": 19,
       "type": "NOT_RESPONDED",
       "survey_id": 367,
       "nps_channel_id": 545,
       "custom_interval": null,
       "frequency": "Days",
       "subject": null,
       "body": null
   }
]

                                

NPS Share Reuse

POST

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

Path Parameters
Name	Type	Description
survey_id	number	ID of the survey
channel_id	number	ID of the channel

Arguments for API Call
Name	Type	Description
contacts	array	Array of contacts
contactLists	array	Array of contact lists

curl --request POST \
  --url 'https://api.surveysparrow.com/v1/nps/{survey_id}/email/{channel_id
}' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data-raw '{
    "contacts": [{
"email":"johndoe@example.com",
"variables":{}
}],
    "contactLists": [{
"Id": 5,
"variables":{}
}]
    }'

                                

{
    "id": 27,
    "type": "EMAIL",
    "properties": {
        "email": {
            "body": "",
            "subject": "Your feedback matters! Help us serve you better.",
            "replyEmail": "vjk-local@surveysparrow.com"
        },
        "acceptAnonymousResponse": false,
        "isTemplate": true
    },
    "npsDelayed": null
}
                                

EMP360

Create Invite

POST

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

Path Parameters
Name	Description
surveyId	ID of the Survey

Body
Name	Description
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
Name	Description
surveyId	ID of the Survey
subjectId	ID of the subject

Body
Name	Description
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
Name	Description
surveyId	ID of the Survey

Body
Name	Description
pageNo	Page no of the results user want to retrieve (starts from 1)
pageLimit	No. 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
Name	Description
surveyId	ID of the Survey
subjectId	ID of the subject

Body
Name	Description
pageNo	Page no of the results user want to retrieve (starts from 1)
pageLimit	No. 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
Name	Description
surveyId	ID of the Survey
subjectId	ID of the subject

Body
Name	Description
pageNo	Page no of the results user want to retrieve (starts from 1)
pageLimit	No. 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)
            }
        }
    ]
}



                                    

Audit Logs (Elite)

Get Audit Logs

GET

https://api.surveysparrow.com/v1/audit-logs

Query Parameters
Name	Type	Required	Description
maxResults	number min(1),max(500)	No	Max number of results
eventType	string	No	Get logs of particular event type
page	number	No	Page no
user	string	No	Name or email of the user to look changes for
startDate	date	No	Logs after this date
endDate	date	No	Logs before this date

CURL --request  GET  https://api.surveysparrow.com/v1/audit-logs?maxResults=30&page=1
--header 'Authorization: Bearer <token>’\
                                

{
   "list": [
       {
           "object": "question",
           "question": {
               "id": "250"
           },
           "survey": {
               "id": "16",
               "name": "rating"
           },
           "id": 57757,
           "event": "SURVEY_EDITED",
           "operation": "Delete",
           "device": "COMPUTER",
           "ipAddress": "127.0.0.1",
           "time": "2020-12-09T11:53:00.713Z",
           "actor": {
               "id": 2,
               "email": "johndoe@gmail.com",
               "name": "john doe"
           },
           "message": "john doe has deleted a question of Id 250 in survey rating"
       },
       {
           "object": "choice",
           "choice": {
               "id": "250",
               "name": "b"
           },
           "question": {
               "id": "250"
           },
           "survey": {
               "id": "16",
               "name": "rating"
           },
           "id": 57756,
           "event": "SURVEY_EDITED",
           "operation": "Edit",
           "device": "COMPUTER",
           "ipAddress": "127.0.0.1",
           "time": "2020-12-09T11:52:47.499Z",
           "actor": {
               "id": 2,
               "email": "johndoe@gmail.com",
               "name": "john doe"
           },
           "message": "john doe has edited choice for questionId 250 of survey rating"
       }
   ],
   "count": 57484,
   "hasNextPage": true}
                                

Get Single Log Details

GET

https://api.surveysparrow.com/v1/audit-logs/{id}

Path Parameters
Name	Type	Required	Description
id	number	Yes	Id of the auditLog

CURL --request  GET  https://api.surveysparrow.com/v1/audit-logs/5700
--header 'Authorization: Bearer <token>’\
                                

{
   "object": "contact",
   "contact": {
       "id": "14395",
       "email": "john+nps84@surveysparrow.com"
   },
   "id": 5700,
   "event": "CONTACT_DELETED",
   "operation": "Delete",
   "device": "COMPUTER",
   "ipAddress": "127.0.0.1",
   "time": "2020-11-28T14:00:49.952Z",
   "actor": {
       "id": 2,
       "email": "johndoe@gmail.com",
       "name": "john doe"
   },
   "message": "john doe has deleted contact john+nps84@surveysparrow.com"
}

                                

Subscribe To Audit Logs Events

(Same like webhook -- for testing team)

POST

https://api.surveysparrow.com/v1/audit-logs/events/subscribe

SUPPORTED eventType

SURVEY_CREATED
SURVEY_EDITED
SURVEY_DELETED
USER_CREATED
USER_EDITED
USER_DELETED
WORKSPAEC_CREATED
WORKSPACE_DELETED
THEME_ADDED
THEME_EDITED
THEME_DELETED
CONTACT_PROPERTY_CREATED
CONTACT_PROPERTY_EDITED
CONTACT_PROPERTY_DELETED
CONTACT_CREATED
CONTACT_UPDATED
CONTACT_DELETED

Arguments for API Call
Name	Type	Mandatory	Description
events	Array	Yes	Name of events
httpMethod	String (GET,POST)	Yes	API call method
url	string	Yes	Url to hit for
headers	Array	No	Array of headers to send in api call

CURL --request  POST https://api.surveysparrow.com/v1/audit-logs/events/subscribe
--header 'Authorization: Bearer <token>’\
--header 'Content-Type: application/json' \


 Body :-    {
  "events":[{"name":"SURVEY_EDITED"}],
  "url":"https://39d6015e6726.ngrok.io/api/internal/surveys",
  "httpMethod":"GET",
  "headers":[{"Authorization":"token"}]
}

                                

{
   "events": [
       {
           "id": 26,
           "event": "SURVEY_EDITED"
       }
   ]
}

                                

Delete Subscribed Event

DELETE

https://api.surveysparrow.com/v1/audit-logs/events/{id}

Path Parameters
Name	Type	Required	Description
id	number	Yes	Id of the Event

CURL --request  DELETE  https://api.surveysparrow.com/v1/audit-logs/events/70
--header 'Authorization: Bearer <token>’\

Status 200

Get All Subscribed Events

GET

https://api.surveysparrow.com/v1/audit-logs/events

Query Parameters
Name	Type	Required	Description
maxResults	number min(1),max(100)	No	Max number of results
eventType	string	No	Get particular event type subscriptions
page	number	No	Page no

CURL --request  GET  https://api.surveysparrow.com/v1/audit-logs/events
--header 'Authorization: Bearer <token>’\

{
   "events": [
       {
           "id": 27,
           "event": "SURVEY_EDITED",
           "url": "https://b9ecca952d42.ngrok.io/audit",
           "httpMethod": "GET",
           "headers": []
       }
   ],
   "count": 1,
   "hasNextPage": false
}

                                