Doorbell.io logoDoorbell.io

API documentation

Basics

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

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

Each access token is granted one or more scopes. Endpoints that only read data require the read scope, while endpoints that create, update, or delete data require the write scope. The required scope is shown next to each endpoint below.

Authentication

  1. Generate an access token

    Create access token

  2. 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 ACCESS-TOKEN

    For example:

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

Endpoints

GET /users/me scope: read

Get the currently authenticated user

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 1,
        "email": "me@example.com",
        "name": "George"
    }
}

GET /applications scope: read

Get all applications

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": [
        {
            "id": 1,
            "organization_id": 0,
            "name": "Loccit",
            "url": null,
            "average_first_reply_time": 21600,
            "target_average_first_reply_time": 43200,
            "keys": {
                "javascript": "jULOnlkXobxdYAoQtIvMuLmk2RUvBFvY",
                "ios": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
                "android": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
                "api": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
                "email": "feedback-1-GnfFg7LEaea6dA0Z5WTNR2zUH2j4pCjW@feedback.doorbell.io"
            },
            "created_at": 1778290391,
            "updated_at": 1779931991
        },
        {
            "id": 17,
            "organization_id": 0,
            "name": "Doorbell",
            "url": null,
            "average_first_reply_time": 2940,
            "target_average_first_reply_time": 10800,
            "keys": {
                "javascript": "dAPl9EVrh310fhvuO0QWaxYOiFkUiZbz",
                "ios": "nHVLQL85khZ1nkSzPHhM0mmRMLtsn81V",
                "android": "nHVLQL85khZ1nkSzPHhM0mmRMLtsn81V",
                "api": "nHVLQL85khZ1nkSzPHhM0mmRMLtsn81V",
                "email": "feedback-17-C4nvzNdCZKi5lSn37GKiCjbgVAwqawCk@feedback.doorbell.io"
            },
            "created_at": 1778290391,
            "updated_at": 1779931991
        }
    ]
}

POST /applications scope: read

Create a new application

Request Parameters

Name Description Example
name The name of an application 1
url The URL of an application
logo The logo of the application (ensure you're making a multipart/form-data request to upload the file)
organization_id The ID of the organization

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 1,
        "organization_id": 0,
        "name": "Loccit",
        "url": null,
        "average_first_reply_time": 21600,
        "target_average_first_reply_time": 43200,
        "keys": {
            "javascript": "jULOnlkXobxdYAoQtIvMuLmk2RUvBFvY",
            "ios": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "android": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "api": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "email": "feedback-1-GnfFg7LEaea6dA0Z5WTNR2zUH2j4pCjW@feedback.doorbell.io"
        },
        "created_at": 1778290391,
        "updated_at": 1779931991
    }
}
404 text/plain Invalid application

GET /applications/{id} scope: read

Get a single application

Request Parameters

Name Description Example
id ID of an application 1

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 1,
        "organization_id": 0,
        "name": "Loccit",
        "url": null,
        "average_first_reply_time": 21600,
        "target_average_first_reply_time": 43200,
        "keys": {
            "javascript": "jULOnlkXobxdYAoQtIvMuLmk2RUvBFvY",
            "ios": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "android": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "api": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "email": "feedback-1-GnfFg7LEaea6dA0Z5WTNR2zUH2j4pCjW@feedback.doorbell.io"
        },
        "created_at": 1778290391,
        "updated_at": 1779931991
    }
}
404 text/plain Invalid application

POST /applications/{id} scope: read

Update a single application

Request Parameters

Name Description Example
name The name of an application 1
url The URL of an application
logo The logo of the application (ensure you're making a multipart/form-data request to upload the file)
organization_id The ID of the organization

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 1,
        "organization_id": 0,
        "name": "Loccit",
        "url": null,
        "average_first_reply_time": 21600,
        "target_average_first_reply_time": 43200,
        "keys": {
            "javascript": "jULOnlkXobxdYAoQtIvMuLmk2RUvBFvY",
            "ios": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "android": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "api": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "email": "feedback-1-GnfFg7LEaea6dA0Z5WTNR2zUH2j4pCjW@feedback.doorbell.io"
        },
        "created_at": 1778290391,
        "updated_at": 1779931991
    }
}
404 text/plain Invalid application

PUT /applications/{id} scope: read

Update a single application (equivalent to POST)

Request Parameters

Name Description Example
name The name of an application 1
url The URL of an application
logo The logo of the application (ensure you're making a multipart/form-data request to upload the file)
organization_id The ID of the organization

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 1,
        "organization_id": 0,
        "name": "Loccit",
        "url": null,
        "average_first_reply_time": 21600,
        "target_average_first_reply_time": 43200,
        "keys": {
            "javascript": "jULOnlkXobxdYAoQtIvMuLmk2RUvBFvY",
            "ios": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "android": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "api": "TkbfMx8d96MPy5URGJNjJCeSxl7slqHj",
            "email": "feedback-1-GnfFg7LEaea6dA0Z5WTNR2zUH2j4pCjW@feedback.doorbell.io"
        },
        "created_at": 1778290391,
        "updated_at": 1779931991
    }
}
404 text/plain Invalid application

GET /applications/{id}/feedback scope: read

Get the feedback of the application

Request Parameters

Name Description Example
id ID of an application 1
archived Set to true or 1 to get the archived feedback (query string parameter) 1

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": [
        {
            "id": 12,
            "email": "member@example.com",
            "gravatar": "https:\/\/secure.gravatar.com\/avatar\/a4fae232e2bfebd9f4dc8d7cb6caecb2?s=64&d=mm",
            "message": "My feedback is that I am very happy with the service",
            "permalink": "https:\/\/doorbell.io\/applications\/1\/feedback\/12",
            "sentiment": "positive",
            "member": {
                "id": 23,
                "email": "member@example.com",
                "name": "George Customer",
                "created_at": 1778002350,
                "updated_at": 1780968791
            },
            "attachments": [],
            "is_anonymous": false,
            "can_reply": true,
            "archived": false,
            "first_reply_time": null,
            "last_reply_time": 1780968791,
            "ip_address": "216.73.216.26",
            "user_agent": "Mozilla\/5.0 AppleWebKit\/537.36 (KHTML, like Gecko; compatible; ClaudeBot\/1.0; +claudebot@anthropic.com)",
            "properties": [],
            "created_at": 1780968791,
            "updated_at": 1780968791,
            "replies": []
        }
    ]
}
404 text/plain Invalid application

GET /applications/{id}/feedback/{feedback_id} scope: read

Get the specific thread of the application

Request Parameters

Name Description Example
id ID of an application 1
feedback_id ID of an feedback thread 12

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 12,
        "email": "member@example.com",
        "gravatar": "https:\/\/secure.gravatar.com\/avatar\/a4fae232e2bfebd9f4dc8d7cb6caecb2?s=64&d=mm",
        "message": "My feedback is that I am very happy with the service",
        "permalink": "https:\/\/doorbell.io\/applications\/1\/feedback\/12",
        "sentiment": "positive",
        "member": {
            "id": 23,
            "email": "member@example.com",
            "name": "George Customer",
            "created_at": 1778002350,
            "updated_at": 1780968791
        },
        "attachments": [],
        "is_anonymous": false,
        "can_reply": true,
        "archived": false,
        "first_reply_time": null,
        "last_reply_time": 1780968791,
        "ip_address": "216.73.216.26",
        "user_agent": "Mozilla\/5.0 AppleWebKit\/537.36 (KHTML, like Gecko; compatible; ClaudeBot\/1.0; +claudebot@anthropic.com)",
        "properties": [],
        "created_at": 1780968791,
        "updated_at": 1780968791,
        "replies": []
    }
}
404 text/plain Invalid application

GET /applications/{id}/tags scope: read

Get all tags configured on the application

Request Parameters

Name Description Example
id ID of an application 1

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": [
        {
            "id": 4,
            "name": "bug",
            "color": "#e74c3c",
            "feedback_count": 12,
            "archived_feedback_count": 3,
            "total_feedback_count": 15
        }
    ]
}
404 text/plain Invalid application

GET /applications/{id}/replies scope: read

Get all replies sent on an application's feedback threads

Request Parameters

Name Description Example
id ID of an application 1
date Restrict to replies created on a single date (Y-m-d, query string parameter) 2026-06-09
limit Maximum number of replies to return (default 50, query string parameter) 50
offset Number of replies to skip (default 0, query string parameter)

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": [
        {
            "id": 892,
            "type": "reply",
            "email": "reply@example.com",
            "gravatar": "https:\/\/www.gravatar.com\/avatar\/abc123?s=64&d=mm",
            "message": "This is the reply message",
            "attachments": [],
            "user": [],
            "created_at": 1780966092,
            "reply_from_agent": true,
            "feedback_id": 12,
            "feedback": {
                "id": 12,
                "email": "member@example.com",
                "message": "My feedback is that I am very happy with the service",
                "sentiment": "pos",
                "archived": false,
                "created_at": 1780965192,
                "updated_at": 1780966092
            }
        }
    ],
    "pagination": {
        "total": 1
    }
}
404 text/plain Invalid application

GET /organizations scope: read

Get all organizations the authenticated user belongs to

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": [
        {
            "id": 7,
            "name": "Acme Inc.",
            "created_at": 1773019991,
            "updated_at": 1780795991
        }
    ]
}

GET /organizations/{id} scope: read

Get a single organization the authenticated user belongs to

Request Parameters

Name Description Example
id ID of an organization 7

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 7,
        "name": "Acme Inc.",
        "created_at": 1773019991,
        "updated_at": 1780795991
    }
}
404 text/plain Invalid organization

PATCH /applications/{id}/feedback/{feedback_id} scope: write

Archive or unarchive a feedback thread

Request Parameters

Name Description Example
id ID of an application 1
feedback_id ID of a feedback thread 12

Request Body

Content-Type: application/json
Name Required Description Example
archived Send the JSON boolean true to archive the thread, or false to unarchive it true

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 12,
        "email": "member@example.com",
        "gravatar": "https:\/\/secure.gravatar.com\/avatar\/a4fae232e2bfebd9f4dc8d7cb6caecb2?s=64&d=mm",
        "message": "My feedback is that I am very happy with the service",
        "permalink": "https:\/\/doorbell.io\/applications\/1\/feedback\/12",
        "sentiment": "positive",
        "member": {
            "id": 23,
            "email": "member@example.com",
            "name": "George Customer",
            "created_at": 1778002350,
            "updated_at": 1780968791
        },
        "attachments": [],
        "is_anonymous": false,
        "can_reply": true,
        "archived": false,
        "first_reply_time": null,
        "last_reply_time": 1780968791,
        "ip_address": "216.73.216.26",
        "user_agent": "Mozilla\/5.0 AppleWebKit\/537.36 (KHTML, like Gecko; compatible; ClaudeBot\/1.0; +claudebot@anthropic.com)",
        "properties": [],
        "created_at": 1780968791,
        "updated_at": 1780968791,
        "replies": []
    }
}
400 text/plain Nothing sent to update
404 text/plain Invalid application
404 text/plain Invalid feedback
500 text/plain Could not update feedback

POST /applications/{id}/feedback/{feedback_id}/replies scope: write

Send a reply to a feedback thread

Request Parameters

Name Description Example
id ID of an application 1
feedback_id ID of a feedback thread 12

Request Body

Content-Type: application/json
Name Required Description Example
message The reply message to send as the authenticated user Thanks for the feedback!

Responses

HTTP Code Content Type Response Body
200 application/json 
{
    "data": {
        "id": 12,
        "email": "member@example.com",
        "gravatar": "https:\/\/secure.gravatar.com\/avatar\/a4fae232e2bfebd9f4dc8d7cb6caecb2?s=64&d=mm",
        "message": "My feedback is that I am very happy with the service",
        "permalink": "https:\/\/doorbell.io\/applications\/1\/feedback\/12",
        "sentiment": "positive",
        "member": {
            "id": 23,
            "email": "member@example.com",
            "name": "George Customer",
            "created_at": 1778002350,
            "updated_at": 1780968791
        },
        "attachments": [],
        "is_anonymous": false,
        "can_reply": true,
        "archived": false,
        "first_reply_time": null,
        "last_reply_time": 1780968791,
        "ip_address": "216.73.216.26",
        "user_agent": "Mozilla\/5.0 AppleWebKit\/537.36 (KHTML, like Gecko; compatible; ClaudeBot\/1.0; +claudebot@anthropic.com)",
        "properties": [],
        "created_at": 1780968791,
        "updated_at": 1780968791,
        "replies": []
    }
}
400 text/plain The message field is required.
404 text/plain Invalid application
404 text/plain Invalid feedback