Send Batch | QuestionPro API Reference Document

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

Example Request


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

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

Authorization

Key - apiKey

Name: apiKey
Location: query

Request Parameters

Path Parameters

survey-id integer

required

Request Body

Payload

application/json


                       {
                            "emails": ["newrespondent1@domain.com,value for custom variable 1,value for custom variable 2","newrespondent2@domain.com,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": 1234567,
                            "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": ["respondent@emaildoamin.com","john.doe@domain.com"],
                            	"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":["respondent@emaildoamin.com","john.doe@domain.com"],
                            	"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

application/json


                    
                   curl --request POST \
                        --url 'https://{{env}}.questionpro.com/a/api/v2/surveys/{{survey-id}}/batches?apiKey={{apiKey}}' \
                        --header 'Content-Type: application/json' \
                        --data '{
                      "emails": [
                        "newrespondent1@domain.com,value for custom variable 1,value for custom variable 2","newrespondent2@domain.com,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": 1234567 ,
                      "mode": 2
                    }'

Python

application/json


                        import requests

                        url = "https://{{env}}.questionpro.com/a/api/v2/surveys/{{survey-id}}/batches"
                    
                        querystring = {"apiKey":"{{apiKey}}"}
                    
                        payload = "{\n\t\"emails\":["newrespondent1@domain.com,value for custom variable 1,value for custom variable 2","newrespondent2@domain.com,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"],\n\t\"templateID\":1234567\n,\n\t\"mode\":2\n}"
                        headers = {'Content-Type': 'application/json'}
                    
                        response = requests.request("POST", url, data=payload, headers=headers, params=querystring)
                    
                        print(response.text)

PHP

application/json

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@domain.com with any questions.

Thank You
",
                                    "status": 64,
                                    "batchType": 1,
                                    "emailCount": 1,
                                    "emailFrom": "email@domain.com",
                                    "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
                                    }
                                }
                        }

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"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "response"
  ]
}

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

Previous Versions

Migration Guides

Change Log

Organization

Department

User

Folders

Survey

Blocks

Questions

Answers

Email Lists

Email List Addresses

Email Templates

Send Survey

Schedule Invitation

Export Batch

Responses

Datapad

Images

Webhooks

Example Request

Authorization

Request Parameters

Request Body

Example Code

Responses