This is the endpoint used for adding recipients to a survey. It has a limitation of 1000 requests per minute which is reset every minute (at 00:00, not 60 seconds after the last request). Valid Survey id for existing survey needs to be provided.

We automatically filter out duplicate emails and prevent the same email being uploaded and sent more than once every 10 minutes.

If you need to add a large batch of recipients at once, see our documentation for Bulk API

If adding metatags by score type (e.g. thank_you_note_promoter, thank_you_note_passive, thank_you_note_detractor) they will work only if 'Customise based on score' switch is enabled within the web interface (on the design step of the survey).

For thank_you_link_url and thank_you_link_note to work, you will also need to enable the 'Add a link' switch in the web interface.

Using this endpoint, you can also include properties and metatags


You can only add recipients using our API to our email survey

  "send_at": "2018-01-01T09:00:00",
  "recipient": {
    "identity": "[email protected]",
    "identity_type": "email",
    "first_name": "test_first_name",
    "last_name": "test_last_name",
    "properties": [
      {"name": "country", "value": "Germany"},
      {"name": "gender", "value": "male"}
    "metatags": {
      "survey_question": "How likely are you to recommend %[question subject] test_first_name?",
      "question_subject": "metatags",
      "request_for_comment_all": "Tell us a bit more about why you chose %[score] for metatags",
      "thank_you_link_text_all": "example text",
      "thank_you_link_url_all": "",
      "thank_you_note_all": "Thanks for your feedback!"

Response attributes

survey_recipientobjectSurvey recipient information data.
survey_recipient.idstringSurvey recipient id.
survey_recipient.statusstringSurvey recipient status.
survey_recipient.recipientobjectRecipient information data.
survey_recipient.recipient.idstringRecipient id.
survey_recipient.recipient.emailstringRecipient email. Deprecated
survey_recipient.recipient.identitystringRecipient identity.
survey_recipient.recipient.identity_typestringRecipient identity type. One of: email, custom
survey_recipient.recipient.first_namestringRecipient first name.
survey_recipient.recipient.last_namestringRecipient last_name.
survey_recipient.recipient.upload_statusstatusRecipient status. One of: new, found
survey_recipient.survey.idstringSurvey id.
survey_recipient.survey.titlestringSurvey title.
survey_recipient.survey.statusstringSurvey status.
survey_recipient.propertiesarrayList of properties. of the property. of the property.
survey_recipient.metatags.survey_questionstringQuestion of the survey containing reference to question_subject.
survey_recipient.metatags.question_subjectstringSubject of the question.
survey_recipient.metatags.request_for_comment_allstringText for comment page regardless of survey recipient score.
survey_recipient.metatags.request_for_comment_promoterstringText for comment page for promoters.
survey_recipient.metatags.request_for_comment_passivestringText for comment page for passives.
survey_recipient.metatags.request_for_comment_detractorstringText for comment page for detractors.
survey_recipient.metatags.thank_you_note_allstringText for thank you page regardless of survey recipient score.
survey_recipient.metatags.thank_you_note_promoterstringText for thank you page for promoters.
survey_recipient.metatags.thank_you_note_passivestringText for thank you page for passives.
survey_recipient.metatags.thank_you_note_detractorstringText for thank you page for detractors.
survey_recipient.metatags.thank_you_link_text_allstringText for link on thank you page regardless of survey recipient score.
survey_recipient.metatags.thank_you_link_text_promoterstringText for link on thank you page for promoters.
survey_recipient.metatags.thank_you_link_text_passivestringText for link on thank you page for passives.
survey_recipient.metatags.thank_you_link_text_detractorstringText for link on thank you page for detractors.
survey_recipient.metatags.thank_you_link_url_allstringURL for link on thank you page regardless of survey recipient score.
survey_recipient.metatags.thank_you_link_url_promoterstringURL for link on thank you page for promoters.
survey_recipient.metatags.thank_you_link_url_passivestringURL for link on thank you page for passives.
survey_recipient.metatags.thank_you_link_url_detractorstringURL for link on thank you page for detractors.
Click Try It! to start a request and see the response here!