Adding Recipients via API

If you need to add survey recipients programmatically, you can use Unwrap's REST API to add them directly without uploading a CSV file. This is useful for integrating survey sending into your existing workflows or systems.

Prerequisites

Before you can use the API, you'll need:

1. Admin access - You must be an admin on your organization

2. API Token - Create one from your Profile Page

Creating Your API Token

1. Navigate to your Profile Page

2. Look for the API Token section

3. Generate a new token

4. Copy and store it securely - you'll use this as your authorization bearer token

:::warning Keep Your Token Secure Treat your API token like a password. Don't share it or commit it to version control. If compromised, delete it immediately from your Profile Page and create a new one. :::

API Endpoint

The endpoint for adding recipients is:

POST https://surveys.api.production.unwrap.ai/addRecipients

Authentication

Include your API token in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_TOKEN

Request Body

The request body must be JSON with the following structure:

{
  "surveyUuid": "your-survey-uuid-here",
  "recipients": [
    {
      "email": "john@example.com",
      "firstName": "John",
      "lastName": "Doe",
      "metadata": {
        "department": "Engineering",
        "customerType": "Enterprise",
        "accountValue": "100k+"
      }
    }
  ]
}

Field Definitions

• surveyUuid (required): The unique identifier of your survey, found in the Configuration tab of your Survey page.

• recipients (required): An array of recipient objects. Each recipient must contain:

• email (required): A valid email address where the survey will be sent

• firstName (optional): The recipient's first name

• lastName (optional): The recipient's last name

• metadata (optional): An object containing custom metadata fields

  • Use this for question parameters if your survey questions reference them

  • Any metadata you include here can later be imported as Custom Fields on your Unwrap feedback entries when analyzing survey responses

Example Request

Here's a complete example using cURL:

curl -X POST https://surveys.api.production.unwrap.ai/addRecipients \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "surveyUuid": "abc123-def456-ghi789",
    "recipients": [
      {
        "email": "john@example.com",
        "firstName": "John",
        "lastName": "Doe",
        "metadata": {
          "department": "Engineering",
          "role": "Manager"
        }
      },
      {
        "email": "jane@example.com",
        "firstName": "Jane",
        "lastName": "Smith",
        "metadata": {
          "department": "Sales",
          "role": "Director"
        }
      }
    ]
  }'

Using Metadata for Question Parameters

If your survey questions use parameters (like {department} or {customerType}), make sure to include those exact keys in the metadata object.

:::tip Learn About Question Parameters New to question parameters? Check out the Personalizing Questions with Parameters section in Survey Settings to learn how they work. :::

For example:

{
  "email": "user@example.com",
  "metadata": {
    "department": "Sales",
    "product": "Premium Plan"
  }
}

If your question says "How satisfied are you with {product}?", the recipient will see "How satisfied are you with Premium Plan?"

Understanding Survey Snapshots

Just like with CSV uploads, each recipient added via API gets a snapshot of your survey at the moment they're added. If you add recipients and then later change a question, those recipients will still see the original question. This ensures consistency in what each recipient sees.

Response Format

A successful response will return a status code of 200 and confirm the recipients were added. The recipients will then appear in your Recipients table with a "Pending send" status.

If the request fails, you'll receive an error response with a descriptive message explaining what went wrong and how to fix it.

Best Practices

• Test first - Add yourself or test email addresses first to verify everything works correctly

• Secure your token - Store API tokens in environment variables or secure credential managers

• Include metadata - Add any metadata you'll want for analysis when the survey responses come back into Unwrap

• Validate emails - Make sure email addresses are properly formatted before sending them to the API

• Match parameters - If using question parameters, ensure your metadata keys exactly match the parameter names in your survey questions

What Happens Next

After successfully adding recipients via the API:

1. Recipients appear in your Recipients table with "Pending send" status

2. If your survey is active, emails will be queued for sending

3. Recipients receive the survey email

4. You can track their status as they respond

Need to Import Responses?

Once recipients start responding, you can set up an integration to pipe survey responses into a view where you can analyze them alongside your other feedback data.