--- updatedAt: 2025-06-09T22:43:12.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. 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#external-app-add-bulk-external-recipients) 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": "external-apps-api", "version": "1.0" }, "servers": [ { "url": "https://api.zenloop.com/external_app" } ], "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.\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#external-app-add-bulk-external-recipients)\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": "external-app-add-external-recipient", "parameters": [ { "name": "survey_id", "in": "path", "description": "Unique ID of a survey", "schema": { "type": "string" }, "required": true } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "api_key": { "type": "string", "description": "Concatenation of the plugin identifier and a unique user key.", "default": "plugin.key" }, "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." } }, "type": "object" } }, "metatags": { "type": "object", "description": "List of metatags", "properties": {} } }, "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." } } } } } } } }, "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 } ```