API

Introduction

The Downright API sends survey invitations from your own systems. It sends into a survey you have already created, so the question, the language and the reporting all come from that survey and one integration reports as a single line.

Base URL

https://www.usedownright.com/api/v1

Every request and response is JSON. There is no versioning beyond the /v1 in the path.

Authentication

Pass your API key as a bearer token on every request.

You will find your key in your dashboard, under API, once you have an account.

curl "https://www.usedownright.com/api/v1/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Emails one person their own one-click survey. The same throttling, unsubscribe and quota rules apply as when you send from the dashboard, so a contact who has opted out or was surveyed recently is skipped rather than mailed again.

Body

Scheduling returns 202 rather than 200. The unsubscribe, throttling and quota rules are checked again at the moment of sending rather than when you scheduled, so somebody who unsubscribes on Tuesday will not receive on Wednesday something you queued on Monday.

Send an offset or a Z with the timestamp. Without one we read it as UTC, which is rarely the hour you meant. The same option exists in the app, under More options when you create an email survey — there it applies to the whole list at once, while here it is per invitation.

Example

curl -X POST "https://www.usedownright.com/api/v1/surveys/SURVEY_ID/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "jane@example.com",
    "contact_name": "Jane Doe",
    "locale": "it"
  }'

Response

{
  "message": "Survey sent successfully",
  "survey_id": "SURVEY_ID"
}

Example: send it on Monday morning instead

curl -X POST "https://www.usedownright.com/api/v1/surveys/SURVEY_ID/invitations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "jane@example.com",
    "deliver_at": "2026-09-07T09:00:00Z"
  }'

Response 202

{
  "message": "Survey scheduled",
  "survey_id": "SURVEY_ID",
  "deliver_at": "2026-09-07T09:00:00Z"
}

Lists the email surveys you can send into, newest first. Use it to discover an id rather than hard-coding one. Link surveys are not listed: they collect answers from a URL and have nothing to send.

Example

curl "https://www.usedownright.com/api/v1/surveys" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "surveys": [
    {
      "id": "SURVEY_ID",
      "name": "Post-purchase survey",
      "survey_type": "NPS",
      "status": "active"
    }
  ]
}

Creates a survey, so an integration can set itself up rather than waiting for somebody to open the dashboard.

Body

Response

{
  "id": "SURVEY_ID",
  "name": "Receipt QR code",
  "survey_type": "CSAT",
  "channel": "link",
  "status": "active",
  "url": "https://www.usedownright.com/s/SLUG"
}

url appears only for a link survey; an email survey has nothing public to point at.

Reads answers back, newest first. Webhooks are how you react to an answer; this is how you make sure you have all of them. Any integration that runs long enough misses a webhook eventually, and this is what makes that survivable.

Query

Example

curl "https://www.usedownright.com/api/v1/surveys/SURVEY_ID/responses?since=2026-08-01T00:00:00Z" \\
  -H "Authorization: Bearer KEY"

Getting notified when somebody answers

Set an endpoint under Settings → Webhook and we POST to it as answers arrive. One URL per account; the payload names the survey, so a receiver that wants to treat the receipt QR code differently from the post-support survey can branch on it.

This is what most people use instead of an integration: point it at a Zapier or Make catch hook and you can raise a Slack message, write a row to a sheet, or open a ticket, without us having built any of those.

Payload

{
  "event": "response.created",
  "survey":   { "id": "SURVEY_ID", "name": "Receipt QR code",
                "question": "NPS", "channel": "link" },
  "response": { "id": "RESPONSE_ID", "score": 3,
                "comment": null, "answered_at": "2026-08-27T09:14:00Z" },
  "contact":  null,
  "account":  { "name": "Acme Coffee" },
  "sent_at":  "2026-08-27T09:14:01Z"
}

contact is absent entirely on an answer from a link survey, rather than present and empty: nobody was identified, as opposed to somebody whose details we failed to include.

The two events, and which one you want

Answering happens in two steps. Somebody picks a score, and the comment box appears afterwards. They may write something seconds later, minutes later, or never. So there are two events, and choosing the wrong one is the most common way to be disappointed by this webhook.

Which to listen for

• Alerting a human about an unhappy customer: listen for response.updated. A Slack message saying somebody scored 3, without the reason, gives whoever reads it nothing to act on — and the reason is exactly what the second event carries.
• Counting, scoring, dashboards: listen for response.created. The score is final at that point and waiting adds nothing.
• Writing to a CRM: handle both and update the same record. response.id is stable across the two, so the second event should overwrite the row the first created rather than adding one.

Verifying a call really came from us

Every call carries these headers. Check the signature before trusting the body: your endpoint is a public URL, and without this anybody who finds it can tell you a customer is furious.

# Ruby
expected = OpenSSL::HMAC.hexdigest('SHA256', ENV['DOWNRIGHT_SECRET'],
                                   "#{timestamp_header}.#{raw_body}")
ActiveSupport::SecurityUtils.secure_compare(expected, signature_header)

Retries, and what we expect back

• Answer 2xx and we consider it delivered. Anything else is a failure.
• We retry after 1 minute, 5 minutes, 30 minutes and 2 hours, then stop.
• We wait 5 seconds for a reply. Do the slow part after answering, not before.
• Because we retry, the same event can arrive twice. Deduplicate on the event id.
• Settings → Webhook shows recent deliveries with their status codes, so “did it fire?” has an answer.
• Only https endpoints on public addresses are accepted.

Responses & errors

Two of these are deliberately not errors: a contact who was surveyed recently, or who is being skipped by your throttling settings, returns 200 with a message. Nothing went wrong, and an integration should not treat it as a failure.

Languages

Language resolves in three steps: the contact's own, then the survey's, then your account default. Send locale when you know what language the person reads and leave it out when you do not. A language outside this list is ignored rather than rejected, so an invitation is still delivered.