API documentation

Basics

This is the API for developers to extend Doorbell. You can register clients, and interact with Doorbell's data (applications, organizations, existing feedback thread, etc).

The API is in private beta at the moment, so client registration isn't available yet.

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

Authentication

Doorbell's API uses OAuth 2.0 for authorizing clients.

The OAuth flow is:

  1. Redirect users to request access

    GET https://doorbell.io/oauth/authorize
    Parameters
    Name Type Required Description
    client_id string The client ID you received from Doorbell.
    redirect_uri string The URL in your app where users will be sent after authorization.
    response_type string Expected value: "code".
    scope string A comma separated list of scopes (read, write). If not provided, scope defaults to read and write.
  2. Doorbell redirects back to your site

    If the user accepts your request, Doorbell redirects back to your site with a temporary code in a code parameter.

    Exchange this for an access token:

    POST https://doorbell.io/oauth/access_token
    Parameters
    Name Type Required Description
    client_id string The client ID you received from Doorbell.
    client_secret string The client secret you received from Doorbell.
    code string The code you received as a response to the first step.
    grant_type string Expected value: "authorization_code".
    redirect_uri string The URL in your app where users will be sent after authorization.
    Response

    By default, the response will take the following form:

    {
        "access_token":"0HFosSpw1y3wVkFo2jAERwuwdsYF0Llgq7Cu0vRM",
        "token_type":"bearer",
        "expires":4553103780,
        "expires_in":3153600000,
        "refresh_token":"2yO1kyvr9JpgbWKGoJ1yMPRuHxHAUYaBuUZjihkh"
    }
  3. Use the access token to access the API

    You need to send the access token you got with each authenticated request to the API. It needs to be included as a request header:

    Authorization: Bearer OAUTH-ACCESS-TOKEN

    For example:

    curl -H "Authorization: Bearer OAUTH-ACCESS-TOKEN" https://doorbell.io/api/applications

Endpoints

GET /applications

Get all applications

Get all applications of the authorized user.

Responses

HTTP Code Content Type Response Body
200 application/json
{
    "data": [
        {
            "id": 1,
            "name": "Loccit",
            "average_first_reply_time": 21600,
            "target_average_first_reply_time": 43200,
            "created_at": 1485122818,
            "updated_at": 1486764418
        },
        {
            "id": 17,
            "name": "Doorbell",
            "average_first_reply_time": 2940,
            "target_average_first_reply_time": 10800,
            "created_at": 1485122818,
            "updated_at": 1486764418
        }
    ]
}

GET /applications/{id}

Get a single application

Get an application of the authorized user.

Request Parameters

Name Description Example
id ID of an application 17

Responses

HTTP Code Content Type Response Body
200 application/json
{
    "data": {
        "id": 1,
        "name": "Loccit",
        "average_first_reply_time": 21600,
        "target_average_first_reply_time": 43200,
        "created_at": 1485122818,
        "updated_at": 1486764418
    }
}
404 text/plain Invalid application

POST /applications/{id}/notifications/slack

Add Slack notifications

Add Slack notifications to an app.

Request Parameters

Name Description Example
id ID of your Doorbell application 17

Request Body

Content-Type: application/json
Name Required Description Example
url The Slack webhook URL https://my.slack.com/services/hooks/incoming-webhook?token=E23VPLXXXXX
channel The channel you want the notifications to be sent to #notifications

Responses

HTTP Code Content Type Response Body
200 text/plain Slack is successfully set up
400 text/plain The url field is required.
400 text/plain The url format is invalid.
400 text/plain Invalid Slack webhook URL
404 text/plain Invalid application
500 text/plain Slack was not successfully set up

POST /applications/{id}/notifications/woopra

Add Woopra notifications

Add Woopra notifications to an app.

Request Parameters

Name Description Example
id ID of your Doorbell application 17

Request Body

Content-Type: application/json
Name Required Description Example
url The Woopra webhook URL

Responses

HTTP Code Content Type Response Body
200 text/plain Woopra is successfully set up
400 text/plain The url field is required.
400 text/plain The url format is invalid.
400 text/plain Invalid Woopra webhook URL
404 text/plain Invalid application
500 text/plain Woopra was not successfully set up

DELETE /applications/{id}/notifications/slack

Remove Slack notifications

Remove Slack notifications from an app.

Request Parameters

Name Description Example
id ID of your Doorbell application 17

Responses

HTTP Code Content Type Response Body
200 text/plain Slack was successfully removed
404 text/plain Invalid application
500 text/plain Slack was not successfully removed

DELETE /applications/{id}/notifications/woopra

Remove Woopra notifications

Remove Woopra notifications from an app.

Request Parameters

Name Description Example
id ID of your Doorbell application 17

Responses

HTTP Code Content Type Response Body
200 text/plain Woopra was successfully removed
404 text/plain Invalid application
500 text/plain Woopra was not successfully removed