Single send

Send a survey to one or more recipients directly by email, SMS, or WhatsApp — without creating a contact list first.

You can attach custom attributes to each recipient by passing the attributes object. These values will be stored alongside the response and can be used for filtering and segmentation in the dashboard (e.g. plan, country, customer_id).

By default the survey is sent immediately. Use the scheduled_at parameter to delay delivery.

You can create a recipient entry without sending the survey by passing send: false. This is useful if you want to handle the sending yourself and later import response data via the API.

Survey throttling

If a recipient has already been sent a survey from the same form within the throttling interval configured on your account, the request will be accepted but the message will not be delivered until the interval has passed. You can override the throttling baseline for a recipient by passing last_sent_at.

Endpoint

POST

https://api.responsly.com/v1/distributions/send

Body parameters

Name	Type	Description
form_id	string	ID of the survey to send. Required.
recipients	array	List of recipient objects. Required. At least one recipient must be provided.
recipients[].email	string	Email address of the recipient. Required if channel is email or not provided.
recipients[].phone_number	string	Phone number in E.164 format (e.g. +17132746524). Required if channel is sms or whatsapp. Must start with + followed by the country code and digits only — no spaces or punctuation.
recipients[].name	string	Full name of the recipient. Used to personalise the message greeting.
recipients[].locale	string	Locale to use for the survey experience. Composed of a lowercase ISO 639-1 language code and an optional uppercase ISO 3166-1 alpha-2 country code separated by a hyphen. Example: pl, en, de, zh-CN. Defaults to the locale configured on the form.
recipients[].attributes	object	Custom key-value pairs attached to the recipient’s response. You can add as many keys as you need. See special attributes for reserved keys that control the survey experience.
recipients[].last_sent_at	string	ISO 8601 datetime (UTC) to manually set the time this recipient was last surveyed. Used by the throttling system to determine eligibility.
channel	string	Delivery channel. Allowed values: email, sms, whatsapp. Defaults to email.
send	boolean	Set to false to register the recipients without sending the survey. Defaults to true.
scheduled_at	string	ISO 8601 datetime (UTC) at which the survey should be sent. Ignored when send is false. Omit to send immediately. Example: 2024-09-01T09:00:00Z.
expires_at	string	ISO 8601 datetime (UTC) after which the survey link will no longer be accessible.
type	string	Link type. Allowed values: one_time (each link can only be used once), anonymous (responses are not tied to the recipient). Defaults to one_time.

Special attributes

The following reserved keys inside attributes let you customise the survey experience per recipient:

Key	Description
email_subject	Custom subject line for the survey email (max 150 characters).
intro_message	Custom introductory message shown in the survey email (max 300 characters).
thank_you_message	Custom message displayed on the thank-you page after the survey is completed.
thank_you_link_text	Label for the call-to-action link on the thank-you page.
thank_you_link_url	URL for the call-to-action link on the thank-you page.

Request

cURL

curl --request POST \
  --url 'https://api.responsly.com/v1/distributions/send' \
  --header 'Authorization: Bearer <Access Token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "form_id": "YOUR_FORM_ID",
    "channel": "email",
    "type": "one_time",
    "scheduled_at": "2024-09-01T09:00:00Z",
    "expires_at": "2024-09-15T23:59:59Z",
    "recipients": [
      {
        "email": "jane@example.com",
        "name": "Jane Doe",
        "locale": "pl",
        "attributes": {
          "plan": "pro",
          "country": "US",
          "email_subject": "We would love your feedback!",
          "intro_message": "It will only take a minute.",
          "thank_you_message": "Thank you for your time!",
          "thank_you_link_text": "Back to app",
          "thank_you_link_url": "https://app.example.com"
        }
      }
    ]
  }'

Response

{
  "items": [
    {
      "email": "jane@example.com",
      "name": "Jane Doe",
      "channel": "email",
      "locale": "pl",
      "link": "https://form.responsly.com/f/ojNEL7gX?token=yvOgZA5VkWDoGlmasQ68lENL8emK67w413",
      "scheduled_at": "2024-09-01T09:00:00.000000Z",
      "expires_at": "2024-09-15T23:59:59.000000Z",
      "type": "one_time",
      "attributes": {
        "plan": "pro",
        "country": "US",
        "email_subject": "We would love your feedback!",
        "intro_message": "It will only take a minute.",
        "thank_you_message": "Thank you for your time!",
        "thank_you_link_text": "Back to app",
        "thank_you_link_url": "https://app.example.com"
      }
    }
  ]
}

Status Code: 201 Created