--- updatedAt: 2025-06-09T22:41:50.000Z agentTools: projectIndex: https://docs.zenloop.com/llms.txt --- # Add External Recipient 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. If your request is made before the previous one has been handled, you will get a `CONFLICT` error. 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](https://docs.zenloop.com/reference#add-bulk-external-recipients-1) 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](http://support.zenloop.com/1-surveys-en/other/choosing-your-properties) and [metatags](https://docs.zenloop.com/v1.0/docs/metatags-implementation) > 📘 You can only add recipients using our API to our email survey ```json Example request { "send_at": "2018-01-01T09:00:00", "recipient": { "identity": "recipient@test.com", "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": "www.example.com", "thank_you_note_all": "Thanks for your feedback!" } } } ``` ## Response attributes | Attribute | Type | Description | | :--------------------------------------------------------------- | :----: | :-------------------------------------------------------------------- | | **survey\_recipient** | object | Survey recipient information data. | | survey\_recipient.**id** | string | Survey recipient id. | | survey\_recipient.**status** | string | Survey recipient status. | | survey\_recipient.**recipient** | object | Recipient information data. | | survey\_recipient.recipient.**id** | string | Recipient id. | | survey\_recipient.recipient.**email** | string | Recipient email. `Deprecated` | | survey\_recipient.recipient.**identity** | string | Recipient identity. | | survey\_recipient.recipient.**identity\_type** | string | Recipient identity type. One of: `email`, `custom` | | survey\_recipient.recipient.**first\_name** | string | Recipient first name. | | survey\_recipient.recipient.**last\_name** | string | Recipient last\_name. | | survey\_recipient.recipient.**upload\_status** | status | Recipient status. One of: `new`, `found` | | survey\_recipient.survey.**id** | string | Survey id. | | survey\_recipient.survey.**title** | string | Survey title. | | survey\_recipient.survey.**status** | string | Survey status. | | survey\_recipient.**properties** | array | List of properties. | | survey\_recipient.properties.**name** | string | Name of the property. | | survey\_recipient.properties.**value** | string | Value of the property. | | survey\_recipient.metatags.**survey\_question** | string | Question of the survey containing reference to question\_subject. | | survey\_recipient.metatags.**question\_subject** | string | Subject of the question. | | survey\_recipient.metatags.**request\_for\_comment\_all** | string | Text for comment page regardless of survey recipient score. | | survey\_recipient.metatags.**request\_for\_comment\_promoter** | string | Text for comment page for promoters. | | survey\_recipient.metatags.**request\_for\_comment\_passive** | string | Text for comment page for passives. | | survey\_recipient.metatags.**request\_for\_comment\_detractor** | string | Text for comment page for detractors. | | survey\_recipient.metatags.**thank\_you\_note\_all** | string | Text for thank you page regardless of survey recipient score. | | survey\_recipient.metatags.**thank\_you\_note\_promoter** | string | Text for thank you page for promoters. | | survey\_recipient.metatags.**thank\_you\_note\_passive** | string | Text for thank you page for passives. | | survey\_recipient.metatags.**thank\_you\_note\_detractor** | string | Text for thank you page for detractors. | | survey\_recipient.metatags.**thank\_you\_link\_text\_all** | string | Text for link on thank you page regardless of survey recipient score. | | survey\_recipient.metatags.**thank\_you\_link\_text\_promoter** | string | Text for link on thank you page for promoters. | | survey\_recipient.metatags.**thank\_you\_link\_text\_passive** | string | Text for link on thank you page for passives. | | survey\_recipient.metatags.**thank\_you\_link\_text\_detractor** | string | Text for link on thank you page for detractors. | | survey\_recipient.metatags.**thank\_you\_link\_url\_all** | string | URL for link on thank you page regardless of survey recipient score. | | survey\_recipient.metatags.**thank\_you\_link\_url\_promoter** | string | URL for link on thank you page for promoters. | | survey\_recipient.metatags.**thank\_you\_link\_url\_passive** | string | URL for link on thank you page for passives. | | survey\_recipient.metatags.**thank\_you\_link\_url\_detractor** | string | URL for link on thank you page for detractors. | # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "api", "version": "1.0" }, "servers": [ { "url": "https://api.zenloop.com" } ], "security": [ {} ], "paths": { "/v1/surveys/{survey_id}/survey_recipients": { "post": { "summary": "Add External Recipient", "description": "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.\nIf your request is made before the previous one has been handled, you will get a `CONFLICT` error.\n\nWe automatically filter out duplicate emails and prevent the same email being uploaded and sent more than once every 10 minutes.\n\nIf you need to add a large batch of recipients at once, see our documentation for [Bulk API](https://docs.zenloop.com/reference#add-bulk-external-recipients-1)\n\nIf 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).\n\nFor 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.\n\nUsing this endpoint, you can also include [properties](http://support.zenloop.com/1-surveys-en/other/choosing-your-properties) and [metatags](https://docs.zenloop.com/v1.0/docs/metatags-implementation)", "operationId": "add-recipient-to-email-survey", "parameters": [ { "name": "survey_id", "in": "path", "description": "Unique ID of a survey", "schema": { "type": "string" }, "required": true }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string", "default": "Bearer " } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "properties": { "identity": { "type": "string", "description": "Recipient identity - email address" }, "identity_type": { "type": "string", "description": "Recipient identity type. Allowed values: `email`", "default": "email" }, "email": { "type": "string", "description": "Recipient email address. `Deprecated`" }, "first_name": { "type": "string", "description": "Recipient first name." }, "last_name": { "type": "string", "description": "Recipient last name." }, "properties": { "type": "array", "description": "List of properties.", "items": { "properties": { "name": { "type": "string", "description": "Name of the property." }, "value": { "type": "string", "description": "Value of the property." } }, "required": [ "name", "value" ], "type": "object" } }, "metatags": { "type": "object", "description": "List of metatags", "properties": { "survey_question": { "type": "string", "description": "New question for the survey." }, "question_subject": { "type": "string", "description": "New subject for survey question." }, "thank_you_note_all": { "type": "string", "description": "New message for thank you page." }, "thank_you_note_promoter": { "type": "string", "description": "New message for thank you page for promoter score if thank you by score is enabled." }, "thank_you_note_passive": { "type": "string", "description": "New message for thank you page for passive score if thank you by score is enabled." }, "thank_you_note_detractor": { "type": "string", "description": "New message for thank you page for detractor score if thank you by score is enabled." }, "thank_you_link_url_all": { "type": "string", "description": "New url for thank you page link." }, "thank_you_link_url_promoter": { "type": "string", "description": "New url for thank you page link for promoter score if thank you link by score is enabled." }, "thank_you_link_url_passive": { "type": "string", "description": "New url for thank you page link for passive score if thank you link by score is enabled." }, "thank_you_link_url_detractor": { "type": "string", "description": "New url for thank you page link for detractor score if thank you link by score is enabled." }, "thank_you_link_text_all": { "type": "string", "description": "New text for thank you page link." }, "thank_you_link_text_promoter": { "type": "string", "description": "New text for thank you page link for promoter score if thank you link by score is enabled." }, "thank_you_link_text_passive": { "type": "string", "description": "New text for thank you page link for passive score if thank you link by score is enabled." }, "thank_you_link_text_detractor": { "type": "string", "description": "New text for thank you page link for detractor score if thank you link by score is enabled." }, "request_for_comment_all": { "type": "string", "description": "New message on comment page." }, "request_for_comment_promoter": { "type": "string", "description": "New message on comment page for promoter score if comment by score is enabled." }, "request_for_comment_passive": { "type": "string", "description": "New message on comment page for passive score if comment by score is enabled." }, "request_for_comment_detractor": { "type": "string", "description": "New message on comment page for detractor score if comment by score is enabled." } } } }, "required": [ "identity", "identity_type" ], "type": "object", "description": "Recipient information data." }, "send_at": { "type": "string", "description": "When survey should be send. Date-time in ISO 8601 format in UTC time standard.", "format": "date" } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"survey_recipient\": {\n \"id\": \"b3M5bTNjV0dSTEdoZU9xb2t3WTRwZjhsQzUya0lMaGgycWVUNmZWZ1pJTT0=\",\n \"status\": \"created\",\n \"recipient\": {\n \"id\": \"YzloYlJmL3NaZ21FVk5GVUdiS1NLZGQ5ODZ0ekF1Z0o1WDdSRld6b2xwTT0=\",\n \"email\": \"recipient@test.com\",\n \"identity\": \"recipient@test.com\",\n \"identity_type\": \"email\",\n \"first_name\": \"test_first_name\",\n \"last_name\": \"test_last_name\",\n \"upload_status\": \"new\"\n },\n \"survey\": {\n \"id\": \"eGRiMFIweVc1UDYyMmVBZkRPWnlZdTh0cVBKY2J0TjBaYm0xOXdZRjhpdz0=\",\n \"title\": \"My survey\",\n \"status\": \"active\"\n },\n \"properties\": [\n {\n \"name\": \"country\",\n \"value\": \"Germany\"\n },\n {\n \"name\": \"gender\",\n \"value\": \"male\"\n }\n ],\n \"metatags\": {\n \"survey_question\": \"How likely are you to recommend %[question subject] test_first_name?\",\n \"question_subject\": \"metatags\",\n \"request_for_comment_promoter\": \"Tell us why you chose %[score] as metatags score, promoter\",\n \"request_for_comment_passive\": \"Tell us why you chose %[score] as metatags score, passive\",\n \"request_for_comment_detractor\": \"Tell us why you chose %[score] as metatags score, detractor\",\n \"thank_you_note_promoter\": \"Thanks for your feedback promoting metatags!\",\n \"thank_you_note_passive\": \"Thanks for your feedback about metatags!\",\n \"thank_you_note_detractor\": \"Thanks for your feedback not promoting metatags!\",\n \"thank_you_link_url_promoter\": \"http://www.zenloop.com\",\n \"thank_you_link_url_detractor\": \"http://www.facebook.com\",\n \"thank_you_link_url_passive\": \"http://www.example.com\",\n \"thank_you_link_text_promoter\": \"Metatags Promoter\",\n \"thank_you_link_text_passive\": \"Metatags Passive\",\n \"thank_you_link_text_detractor\": \"Metatags Detractor\"\n }\n }\n}" } }, "schema": { "type": "object", "properties": { "survey_recipient": { "type": "object", "properties": { "id": { "type": "string", "example": "b3M5bTNjV0dSTEdoZU9xb2t3WTRwZjhsQzUya0lMaGgycWVUNmZWZ1pJTT0=" }, "status": { "type": "string", "example": "created" }, "recipient": { "type": "object", "properties": { "id": { "type": "string", "example": "YzloYlJmL3NaZ21FVk5GVUdiS1NLZGQ5ODZ0ekF1Z0o1WDdSRld6b2xwTT0=" }, "email": { "type": "string", "example": "recipient@test.com" }, "identity": { "type": "string", "example": "recipient@test.com" }, "identity_type": { "type": "string", "example": "email" }, "first_name": { "type": "string", "example": "test_first_name" }, "last_name": { "type": "string", "example": "test_last_name" }, "upload_status": { "type": "string", "example": "new" } } }, "survey": { "type": "object", "properties": { "id": { "type": "string", "example": "eGRiMFIweVc1UDYyMmVBZkRPWnlZdTh0cVBKY2J0TjBaYm0xOXdZRjhpdz0=" }, "title": { "type": "string", "example": "My survey" }, "status": { "type": "string", "example": "active" } } }, "properties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "example": "country" }, "value": { "type": "string", "example": "Germany" } } } }, "metatags": { "type": "object", "properties": { "survey_question": { "type": "string", "example": "How likely are you to recommend %[question subject] test_first_name?" }, "question_subject": { "type": "string", "example": "metatags" }, "request_for_comment_promoter": { "type": "string", "example": "Tell us why you chose %[score] as metatags score, promoter" }, "request_for_comment_passive": { "type": "string", "example": "Tell us why you chose %[score] as metatags score, passive" }, "request_for_comment_detractor": { "type": "string", "example": "Tell us why you chose %[score] as metatags score, detractor" }, "thank_you_note_promoter": { "type": "string", "example": "Thanks for your feedback promoting metatags!" }, "thank_you_note_passive": { "type": "string", "example": "Thanks for your feedback about metatags!" }, "thank_you_note_detractor": { "type": "string", "example": "Thanks for your feedback not promoting metatags!" }, "thank_you_link_url_promoter": { "type": "string", "example": "http://www.zenloop.com" }, "thank_you_link_url_detractor": { "type": "string", "example": "http://www.facebook.com" }, "thank_you_link_url_passive": { "type": "string", "example": "http://www.example.com" }, "thank_you_link_text_promoter": { "type": "string", "example": "Metatags Promoter" }, "thank_you_link_text_passive": { "type": "string", "example": "Metatags Passive" }, "thank_you_link_text_detractor": { "type": "string", "example": "Metatags Detractor" } } } } } } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\": {\n \"status\": 400,\n \"code\": \"VALIDATION_ERRORS\",\n \"title\": \"Validation errors occurred.\",\n \"details\": [{\n \"detail\": \"We can't duplicate survey recipients\",\n \"field\": \"survey_recipient\"\n }]\n }\n}" } }, "schema": { "oneOf": [ { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "string", "example": "INVALID_REQUEST" }, "links": { "type": "object", "properties": { "documentation": { "type": "string", "example": "https://docs.zenloop.com/v1.0/reference" } } }, "title": { "type": "string", "example": "Invalid request body." }, "details": { "type": "array", "items": { "type": "object", "properties": { "detail": { "type": "string", "example": "Required property recipient was not present." }, "pointer": { "type": "string", "example": "" } } } } } } } }, { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 400, "default": 0 }, "code": { "type": "string", "example": "VALIDATION_ERRORS" }, "title": { "type": "string", "example": "Validation errors occurred." }, "details": { "type": "array", "items": { "type": "object", "properties": { "detail": { "type": "string", "example": "We can't duplicate survey recipients" }, "field": { "type": "string", "example": "survey_recipient" } } } } } } } } ] } } } }, "401": { "description": "401", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\": {\n \"status\": 401,\n \"code\": \"UNAUTHORIZED\",\n \"title\": \"Invalid or expired token.\"\n }\n}" } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 401, "default": 0 }, "code": { "type": "string", "example": "UNAUTHORIZED" }, "title": { "type": "string", "example": "Invalid or expired token." } } } } } } } }, "403": { "description": "403", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\": {\n \"status\": 403,\n \"code\": \"FORBIDDEN\",\n \"title\": \"Action forbidden. Only allowed for email survey.\"\n }\n}" } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 403, "default": 0 }, "code": { "type": "string", "example": "FORBIDDEN" }, "title": { "type": "string", "example": "Action forbidden. Only allowed for email survey." } } } } } } } }, "404": { "description": "404", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\": {\n \"status\": 404,\n \"code\": \"NOT_FOUND\",\n \"title\": \"Survey not found.\"\n }\n}" } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 404, "default": 0 }, "code": { "type": "string", "example": "NOT_FOUND" }, "title": { "type": "string", "example": "Survey not found." } } } } } } } }, "409": { "description": "409", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\" => {\n \"status\" => 409,\n \"code\" => \"CONFLICT\",\n \"title\" => \"Import still in progress. Please try again later.\"\n }\n}" } } } } }, "429": { "description": "429", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"error\": {\n \"status\": 429,\n \"code\": \"TOO_MANY_REQUESTS\",\n \"title\": \"Rate limit exceeded.\"\n }\n}" } }, "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer", "example": 429, "default": 0 }, "code": { "type": "string", "example": "TOO_MANY_REQUESTS" }, "title": { "type": "string", "example": "Rate limit exceeded." } } } } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [ { "key": "Content-Type", "value": "application/json" } ], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```