Feedback Capture API documentation

Basics

This is the API for capturing user feedback and saving it in Doorbell (if you're planning on writing your own widget).

The base URL for the API is: https://doorbell.io/api

All requests should be POST requests.

Please provide a useful User-Agent header with each request!

Authentication

Doorbell has an application ID and a secret key that need to be used when making API calls. The ID constructs part of the URL in each call (/applications/{id}/{action}), and the key should always be passed as a query string parameter, using the name key. (e.g. https://doorbell.io/api/applications/1/open?key=key-goes-here)

To obtain an application ID/key, you need to register here on Doorbell, create an application, go to the setup page, and copy the ID/Key from the API tab.

Endpoints

POST /applications/{id}/open

Open

Request sent when the form is displayed to the user.

Query string parameters

Name Description
key The application key

Responses

HTTP Code Content Type Response Body
201 plain/text OK
403 plain/text Not authorized
404 plain/text Invalid application

POST /applications/{id}/submit

Submit

Request sent when the form is submitted.

Query string parameters

Name Description
key The application key

Request Body

Content-Type: application/json
Name Required Description Example
email The email address of the user sending feedback hello@example.com
message The feedback message the user has entered Hello! Loving this app!
name The name of the user who is sending feedback John Doe
properties JSON encoded string of properties (of any data type), any extra metadata you want to attach to the message {"user_id":"Z10JF","username":"zarek"}
attachments Array of attachment IDs (get these from uploading to the upload endpoint [182,593,508]
nps The NPS rating the user submitted alongside the message 10
language The language the site/app is using. The response messages will be in the corresponding language, if translated en, es, pt

Responses

HTTP Code Content Type Response Body
201 plain/text Feedback sent!
400 plain/text Your email address is required
400 plain/text Invalid email address
400 plain/text Your message is required
400 plain/text Your message is too short
403 plain/text Not authorized
404 plain/text Application not found

POST /applications/{id}/upload

Upload

Request sent when uploading an attachment (for the subsequent submit request).

The endpoint (on success) will return a JSON array of IDs. These IDs need to be supplied to the submit request afterwards.

Query string parameters

Name Description
key The application key

POST Parameters

  • Multipart form request, including any number of files

Responses

HTTP Code Content Type Response Body
201 application/json A JSON array containing the attachment IDs of the files uploaded
400 plain/text Uploads not enabled
400 plain/text No files found (this could mean an error in how the files are sent)
403 plain/text Not authorized
404 plain/text Invalid application