Send Batch | QuestionPro API Reference Document

Post /surveys/{{survey-id}}/batches

Example Request


https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/batches

The value of environment {{env}} variable depends upon your datacenter. Refer to the Environment page for more details.

Authorization

Security - API Key

Name : api-key

required

Location : Request Header

Type : string

Request Parameters

Path Parameters

survey-id integer

required

Request Body

Payload

application/json


                       {
                            "emails": ["[email protected],value for custom variable 1,value for custom variable 2","[email protected],value for custom variable 1,value for custom variable 2,value for custom variable 3,value for custom variable 4,value for custom variable 5" ],
                            "templateID": {{template-id}},
                            "mode": 2
                        }

Request body for different values of mode in the API payload

1 : Send invites to an existing email list using an existing email template

application/json


                            {
                            	"templateID": {{template-id}},
                            	"emailListID": {{email-list-id}},
                            	"mode": 1
                            }

2 : Send invites to individual email addresses using an existing email template

application/json


                            {
                            	"emails": ["[email protected]","[email protected]"],
                            	"templateID": {{template-id}},
                            	"mode": 2
                            }

3 : Send invites to existing email list using a custom email template

application/json


                            {
                            	"emailListID": {{email-list-id}},
                            	"emailTemplate": {
                            	"emailSubject": "Lets get it started",
                            	"content": "And the beat goes \r\n boom. Answer the survey: <SURVEY_LINK>"
                            	},
                            		"mode": 3
                            }
                            
                            Note: For this mode,"<SURVEY_LINK>" must be present in the content tag of emailTemplate object.

4 : Send invites to individual email addresses using a custom email template

application/json


                            {
                            	"emails":["[email protected]","[email protected]"],
                            	"emailTemplate":{
                            	"emailSubject":"Lets get it started",
                            	"content":"And the beat goes \r\n boom. Answer the survey: <SURVEY_LINK>"
                            	},
                            		"mode":4
                            }
                            
                             Note: For this mode,"<SURVEY_LINK>" must be present in the content tag of emailTemplate object.

Example Code

cURL

Snippet copied successfully.

application/json


                    
curl --location 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/batches' \
--header 'Content-Type: application/json' \
--header 'api-key: {{api-key}}' \
--data-raw '{
	"emails": ["[email protected],value for custom variable 1,value for custom variable 2","[email protected],value for custom variable 1,value for custom variable 2,value for custom variable 3,value for custom variable 4,value for custom variable 5"],
	"templateID": 490627,
	"mode": 2
}'

Python

Snippet copied successfully.

application/json


import requests
import json

url = "https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/batches"

payload = json.dumps({
  "emails": [
    "[email protected],value for custom variable 1,value for custom variable 2",
    "[email protected],value for custom variable 1,value for custom variable 2,value for custom variable 3,value for custom variable 4,value for custom variable 5"
  ],
  "templateID": 490627,
  "mode": 2
})
headers = {
  'Content-Type': 'application/json',
  'api-key': '{{api-key}}'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

PHP - cURL

Snippet copied successfully.

application/json


<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => 'https://api.questionpro.{{env}}/a/api/v2/surveys/{{survey-id}}/batches',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => '',
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => 'POST',
  CURLOPT_POSTFIELDS =>'{
	"emails": ["[email protected],value for custom variable 1,value for custom variable 2","[email protected],value for custom variable 1,value for custom variable 2,value for custom variable 3,value for custom variable 4,value for custom variable 5"],
	"templateID": 490627,
	"mode": 2
}',
  CURLOPT_HTTPHEADER => array(
    'Content-Type: application/json',
    'api-key: {{api-key}}'
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

Responses

Example

application/json


                         {
                            "response": 
                                  {
                                    "emailBatchID": 1234567,
                                    "surveyID": 7654321,
                                    "userID": 9876543,
                                    "batchName": null,
                                    "subject": "Survey Invitation",
                                    "description": "Email List : Default List-0",
                                    "emailText": "Hello,

We would appreciate your feedback in our online survey. All responses will remain confidential and secure. Thank you in advance for your valuable insights. Your input will be used to ensure that we continue to meet your needs. We appreciate your trust and look forward to serving you in the future.

We have contracted with QuestionPro, an independent research firm, to field your confidential survey responses. Please click on this link to complete the survey:

<SURVEY_LINK>

Please contact [email protected] with any questions.

Thank You
",
                                    "status": 64,
                                    "batchType": 1,
                                    "emailCount": 1,
                                    "emailFrom": "[email protected]",
                                    "creationDate": "2020-11-05T07:14:29.000+00:00",
                                    "emailStatsList": null,
                                    "emailFromName": "null",
                                    "emailBatchStatistics": {
                                        "queuedCount": 0,
                                        "sentCount": 0,
                                        "errorCount": 0,
                                        "startedCount": 0,
                                        "viewedCount": 0,
                                        "takenCount": 0,
                                        "blockedCount": 0,
                                        "participationPendingCount": 0,
                                        "unSubscribedCount": 0
                                    }
                                },
                            "requestID": "4012fedc-e8ce-48ae-b800-6q5ce287987a7dje"
                        }

Schema

application/json

{
  "$schema": "http://json-schema.org/draft-06/schema# ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "batchName": {
          "type": "null"
        },
        "surveyID": {
          "type": "integer"
        },
        "emailStatsList": {
          "type": "null"
        },
        "emailBatchStatistics": {
          "type": "object",
          "properties": {
            "unSubscribedCount": {
              "type": "integer"
            },
            "blockedCount": {
              "type": "integer"
            },
            "queuedCount": {
              "type": "integer"
            },
            "viewedCount": {
              "type": "integer"
            },
            "takenCount": {
              "type": "integer"
            },
            "participationPendingCount": {
              "type": "integer"
            },
            "startedCount": {
              "type": "integer"
            },
            "errorCount": {
              "type": "integer"
            },
            "sentCount": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "unSubscribedCount",
            "blockedCount",
            "queuedCount",
            "viewedCount",
            "takenCount",
            "participationPendingCount",
            "startedCount",
            "errorCount",
            "sentCount"
          ]
        },
        "subject": {
          "type": "string"
        },
        "description": {
          "type": "string"
        },
        "emailText": {
          "type": "string"
        },
        "creationDate": {
          "type": "string"
        },
        "userID": {
          "type": "integer"
        },
        "emailFromName": {
          "type": "string"
        },
        "emailBatchID": {
          "type": "integer"
        },
        "emailFrom": {
          "type": "string",
          "format": "email"
        },
        "batchType": {
          "type": "integer"
        },
        "status": {
          "type": "integer"
        },
        "emailCount": {
          "type": "integer"
        }
      },
      "additionalProperties": false,
      "required": [
        "surveyID",
        "emailBatchStatistics",
        "subject",
        "description",
        "emailText",
        "creationDate",
        "userID",
        "emailFromName",
        "emailBatchID",
        "emailFrom",
        "batchType",
        "status",
        "emailCount"
      ]
    },
    "requestID": {
      "type": "string"
    }
  },
  "additionalProperties": false,
  "required": [
    "response",
    "requestID"
  ]
}

400 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "BAD_REQUEST",
         "httpStatusCode": 400,
         "id" : "1000",
         "message": "Invalid URL parameters",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

401 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "UNAUTHORIZED",
         "httpStatusCode": 401,
         "id" : "1010",
         "message": "Incorrect API Key",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

403 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "FORBIDDEN",
         "httpStatusCode": 403,
         "id" : "1013",
         "message": "The user does not have permission to access the resource",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

404 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "NOT_FOUND",
         "httpStatusCode": 404,
         "id" : "1040",
         "message": "The resource that you're trying to access doesn't exist",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

500 example

application/json


{
    "response": {
     "error": {
         "docs": www.questionpro.com/api/error-codes.html
         "name": "INTERNAL_SERVER_ERROR",
         "httpStatusCode": 500,
         "id" : "1026",
         "message": "We are not able to process your request",
         "resourceUrl":"resource_url"
        }
    }
}

Schema

application/json


{
  "$schema": "http://json-schema.org/draft-06/schema#                                 ",
  "type": "object",
  "properties": {
    "response": {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "docs": {
              "type": "string"
            },
            "resourceUrl": {
              "type": "string"
            },
            "name": {
              "type": "string"
            },
            "id": {
              "type": "string"
            },
            "message": {
              "type": "string"
            },
            "httpStatusCode": {
              "type": "integer"
            }
          },
          "additionalProperties": false,
          "required": [
            "docs",
            "resourceUrl",
            "name",
            "id",
            "message",
            "httpStatusCode"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "error"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

Introduction

Upcoming Changes

Organization

Department

User

Folders

Survey

Blocks

Questions

Answers

Email Lists

Email List Addresses

Email Templates

Send Survey

Schedule Invitation

Export Batch

Responses

Datapad

Response Statistics

Images

Webhooks

Example Request

Authorization

Request Parameters

Request Body

Example Code

Responses