Home
/
Chat
/
Platform API

Organization API

This API allows you to list, view, create and manage your SendBird applications through HTTP requests. Each HTTP request should be authenticated with your organization API key in the request header. The unique API key can be found in your Sendbird Dashboard under Account > Organization settings > General > Organization API key. Note that the organization API key can retrieve token information from all client apps.

HTTP headers

POST /api/v2/applications HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE5.01; Windows NT)
Host: gate.sendbird.com
Content-Type: application/json;charset=utf-8
Content-Length: length
Accept-Language: en-us
Accept-Encoding: gzip, deflate
Connection: Keep-Alive
SENDBIRDORGANIZATIONAPITOKEN: {organization_api_key}
...


Resource representation

The following table shows the list of properties in an organization resource.

List of application properties

Property nameTypeDescription

app_id

string

The unique ID of the application.

app_name

string

The name of the application.

region

nested object

The region information of the application.

premium_features

nested object

Information about premium features used in the application.

push_notification

nested object

The push notification settings used in the application.

auto_event_message

nested object

The auto event message settings used in the application.

created_at

datetime

The date and time when the application was created.

List of feature properties

Property nameTypeDescription

auto_thumbnail

boolean

Indicates the thumbnail auto-generator feature.

translation_tools

boolean

Indicates the message auto-translation feature.

image_moderation

boolean

Indicates the image moderation feature.

data_export

boolean

Indicates the data export feature.

domain_filter

boolean

Indicates the domain filter feature.

profanity_filter

boolean

Indicates the profanity filter feature.

delivery_receipt

boolean

Indicates the delivery receipt feature.

announcement

boolean

Indicates the announcements feature.

supergroup

boolean

Indicates a Supergroup channel.

advanced_analytics

boolean

Indicates the advanced analytics feature.

message_search

boolean

Indicates the message search feature.

List of member properties

Property nameTypeDescription

id

int

A unique ID of the member.

role

string

A role given to the member.

created_at

datetime

The date and time when the member was created.

status

string

The account status of the member. Valid values are ACTIVE and INACTIVE.

*The INACTIVE status indicates that the member's account is deleted.

user.id

int

The unique user ID of the member.

user.email

string

The email address of the member.

user.date_joined

datetime

The date and time when the member joined the organization.

user.is_active

boolean

Indicates whether the member's status is active.

user.profile.id

int

The unique ID of the member's profile.

user.profile.nickname

string

The member's nickname.

user.first_name

string

The member's first name.

user.last_name

string

The member's last name.

organization

int

The unique ID of the organization.

organization_member_role

object

Detailed information about the member's role.


Actions

  • API endpoints in this page are relative to the base URL allocated to your Sendbird application. In this page, the /applications endpoint refers to https://gate.sendbird.com/api/v2/applications.
ActionHTTP request

List applications

GET /applications
Retrieves a list of applications of your organization.

View an application

GET /applications/{app_id}
Retrieves information about an application with a specified application ID.

Create an application

POST /applications
Creates a new application under your organization.

Delete an application

DELETE /applications/{app_id}
Deletes an application with a specified application ID.

Copy application settings

POST applications/copy_settings
Copies the application settings of a specified application ID.

List features

GET /applications/{app_id/}features
Retrieves a list of features with a specified application ID.

Update a feature

PATCH /applications/{app_id}/features
Updates information about a feature with a specified application ID.

List members

GET /organization_members
Retrieves a list of members of your organization.

View a member

GET /organization_members/{member_id}
Retrieves information about a member with a specified member ID.

Update a member

PATCH /organization_members/{member_id}
Updates information about a member with a specified member ID.

List member roles

GET /organization_member_roles
Retrieves a list of member roles of your organization.

Deactivate a member

POST /organization_members/{member_id}/deactivate
Deactivates a member with a specified member ID.


List applications

Retrieves a list of applications of your organization.

HTTP request

GET https://gate.sendbird.com/api/v2/applications

Parameters

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

limit

int

Specifies the number of results to retrieve per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

offset

int

Specifies the number of results to skip before retrieving the next page in the result. This is used to mark the starting index of the next page. (Default: 0)

region_key

string

Restricts the search scope by specifying the code of a region to retrieve a list of applications from. Acceptable values are listed in your dashboard under Account > Organization settings > General > API regions.

?limit=3&offset=3

Response

If successful, this action returns a list of applications in the response body as shown below.

{
    "count": 40,
    "previous": "https://gate.sendbird.com/api/v2/applications?limit=3&offset=3",
    "next": "https://gate.sendbird.com/api/v2/applications?limit=3&offset=6",
    "results": [
        {
            "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "app_name": "sendbird_application_staging",
            "api_token": "80af23e7ec3a51fa2792c249aaf9e8f1e5bd4a6c",
            "region": {
                "region_key": "tokyo-1",
                "region_name": "Tokyo, Japan"
            },
            "created_at": "2020-10-13T06:10:59Z"
        },
        ... # More applications
    ]
}

List of response properties

Property nameTypeDescription

count

int

The total count of applications under your organization.

previous

string

The URL to retrieve the previous page in the result set.

next

string

The URL to retrieve the next page in the result set.

results[]

list

A list of applications.


View an application

Retrieves information about an application with a specified application ID.

HTTP request

GET https://gate.sendbird.com/api/v2/applications/{app_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

app_id

string

Restricts the search scope for the applications whose name contains the specified parameter value. This search is case-insensitive.

Response

If successful, this action returns an application resource in the response body like the following.

{
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "app_name": "sendbird_application_staging",
    "api_token": "80af23e7ec3a51fa2792c249aaf9e8f1e5bd4a6c",
    "region": {
        "region_key": "tokyo-1",
        "region_name": "Tokyo, Japan"
    },
    "created_at": "2020-10-13T06:10:59Z"
}

Create an application

Creates a new application under your organization.

HTTP request

POST https://gate.sendbird.com/api/v2/applications

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

app_name

string

Specifies the name of an application to create. The name is considered case-insensitive in application search.

region_key

string

Specifies the code of a region in which an application is to be created. Acceptable values are listed in your dashboard under Account > Organization settings > General > API regions.

{
    "app_name": "sendbird_application_production",
    "region_key": "tokyo-1"
}

Response

If successful, this action returns an application resource in the response body like the following.

{
    "app_id": "xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "app_name": "sendbird_application_production",
    "api_token": "b0ar34e7acfa15fa2732c249aaf9e8f1e5bd3ew1",
    "region": {
        "region_key": "tokyo-1",
        "region_name": "Tokyo, Japan"
    },
    "created_at": "2020-10-18T06:10:59Z"
}

Delete an application

Deletes tan application with a specified application ID.

HTTP request

DELETE https://gate.sendbird.com/api/v2/applications/{app_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

app_id

string

Specifies a unique ID of the application to delete.

Response

If successful, this action returns an empty body.


Copy application settings

Copies the application settings of a specified application ID.

HTTP request

POST https://gate.sendbird.com/api/v2/applications/copy_settings

Request body

The following table lists the properties of an HTTP request that this action supports.

Properties
RequiredTypeDescription

from_app_id

string

Specifies the application ID you want to copy the settings from.

to_app_id

string

Specifies the application ID you want to copy the settings to.

{
  "from_app_id": "18BD5E50-140A-4B3F-BA9E-876F3B508D44",
  "to_app_id": "0BAF19BE-2C80-477C-8A79-7A225F573195"
}

Response

If successful, this action returns an application resource in the response body like the following.

{
    "app_id": "0DAF19BE-3C80-477C-8A79-7A225F573196",
    "app_name": "Target App",
    "api_token": "b0ar34e7acfa15fa2732c249aaf9e8f1e5bd3ew1",
    "region": {
        "region_key": "north-virginia-2",
        "region_name": "North Virginia 2, USA"
    },
    "created_at": "2021-07-30T02:16:08Z"
}

List features

Retrieves a list of features used in the specified application.

HTTP request

GET https://gate.sendbird.com/api/v2/applications/{app_id}/features

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

app_id

string

Specifies a unique ID of the application to list features.

Response

If successful, this action returns a feature resource in the response body like the following.

{
    "auto_thumbnail": false,
    "translation_tools": false,
    "image_moderation": false,
    "moderation_tools": true,
    "data_export": true,
    "domain_filter": false,
    "profanity_filter": false,
    "delivery_receipt": false,
    "announcement": false,
    "supergroup": true,
    "advanced_analytics": true,
    "message_search": false
}

Update a feature

Updates information about a feature with a specified application ID.

HTTP request

PATCH https://gate.sendbird.com/api/v2/applications/{app_id}/features

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

app_id

string

Specifies a unique ID of the application to update feature information.

{
    "auto_thumbnail": true,
    "domain_filter": true
}

Response

If successful, this action returns a feature resource in the response body like the following.

{
    "auto_thumbnail": true,
    "translation_tools": false,
    "image_moderation": false,
    "moderation_tools": true,
    "domain_filter": true,
    "profanity_filter": false,
    "data_export": true,
    "delivery_receipt": false,
    "announcement": false,
    "supergroup": true,
    "advanced_analytics": true,
    "message_search": true
}

List members

Retrieves a list of members of the specified organization.

HTTP request

GET https://gate.sendbird.com/api/v2/organization_members

Parameters

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

limit

int

Specifies the number of results to retrieve per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

offset

int

Specifies the number of results to skip before retrieving the next page in the result. This is used to mark the starting index of the next page. (Default: 0)

Response

If successful, this action returns a member resource in the response body like the following.

{
    "count": 27,
    "previous": "https://gate.sendbird.com/api/v2/applications?limit=10&offset=0",
    "next": "https://gate.sendbird.com/api/v2/applications?limit=10&offset=20",
    "results": [
        {
            "id": 4,
            "role": "OWNER",
            "created_at": "2021-04-07T08:15:16.542515Z",
            "status": "ACTIVE",
            "user": {
                "id": 8,
                "email": "sample_user@sample.com",
                "date_joined": "2021-04-07T08:15:16.537315Z",
                "is_active": true,
                "profile": {
                    "id": 7,
                    "nickname": "sample_user_nickname"
                },
                "first_name": "",
                "last_name": ""
            },
            "organization": 5,
            "organization_member_role": {
                "name": "OWNER",
                "is_predefined": true
            }
        },
        … # More organization member data
    ]
}

List of response properties

Property nameTypeDescription

count

int

The total number of members in the specified organization.

previous

Nullable
[string]

The URL to retrieve the previous page in the result set.

next

Nullable
[string]

The URL to retrieve the next page in the result set.

results[]

list

A list of members in the specified organization.


View a member

Retrieves information about a member with a specified member ID.

HTTP request

GET https://gate.sendbird.com/api/v2/organization_members/{member_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

member_id

int

The unique ID of the organization member.

Response

If successful, this action returns an application resource in the response body like the following.

{
  "id": 14274,
  "role": "ADMIN",
  "created_at": "2020-12-10T06:12:52Z",
  "status": "ACTIVE",
  "user": {
    "id": 30003989,
    "email": "sample@sample.com",
    "date_joined": "2020-12-10T06:12:52Z",
    "is_active": true,
    "profile": {
      "id": 14388,
      "nickname": "sample_nickname"
    },
    "first_name": "Sample",
    "last_name": "Jack"
  },
  "organization": 13731,
  "organization_member_role": {
    "name": "ADMIN",
    "is_predefined": true
  }
}

Update a member

Updates information about a member with a specified member ID.

HTTP request

PATCH https://gate.sendbird.com/api/v2/organization_members/{member_id}

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

member_id

int

The unique ID of the organization member.

Request body

The 2 properties shown below can't be requested at the same time. If a user requests both properties, an error will be returned.

Optional
Property nameTypeDescription

predefined_role

string

System roles provided by the organization. Valid values are OWNER, ADMIN, BILLING, DESK_ADMIN, DESK_AGENT, CALL_USER, and DEFAULT.

role

string

Role names customizable by the user.

# when the role is predefined
{"predefined_role": "ADMIN"}

# when the role is not predefined (= custom)
{"role": "CUSTOM_ROLE_NAME"}

Response

If successful, this action returns a member resource in the response body like the following.

{
  "id": 14274,
  "role": "ADMIN",
  "created_at": "2020-12-10T06:12:52Z",
  "status": "ACTIVE",
  "user": {
    "id": 30003989,
    "email": "sample@sample.com",
    "date_joined": "2020-12-10T06:12:52Z",

    "is_active": true,
    "profile": {
      "id": 14388,
      "nickname": "sample_nickname"
    },
    "first_name": "Sample",
    "last_name": "Jack"
  },
  "organization": 13731,
  "organization_member_role": {
    "name": "ADMIN",
    "is_predefined": true
  }
}

Deactivate a member

Deactivates a member with a specified member ID.

HTTP request

POST https://gate.sendbird.com/api/v2/organization_members/{member_id}/deactivate

Parameters

The following table lists the parameters that this action supports.

Required
Parameter nameTypeDescription

member_id

int

The unique ID of the organization member.

Response

If successful, this action returns an empty body.


List predefined roles

Retrieves a list of predefined roles of the organization members. In the Sendbird Dashboard, the term is known as SYSTEM ROLE.

HTTP request

GET https://gate.sendbird.com/api/v2/organization_members/predefined_roles

Response

If successful, this action returns a member resource in the response body, showing only the predefined roles.

[
    "OWNER",
    "ADMIN",
    "BILLING",
    "DESK_ADMIN",
    "DESK_AGENT",
    "CALL_USER",
    "DEFAULT"
]

List custom roles

Retrieves a list of custom roles of the organization members.

HTTP request

GET https://gate.sendbird.com/api/v2/organization_members/custom_roles

Parameters

The following table lists the parameters that this action supports.

Optional
Parameter nameTypeDescription

limit

int

Specifies the number of results to retrieve per page. Acceptable values are 1 to 100, inclusive. (Default: 10)

offset

int

Specifies the number of results to skip before retrieving the next page in the result. This is used to mark the starting index of the next page. (Default: 0)

Response

If successful, this action returns a member resource in the response body, showing only the customized roles.

{
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 10000,
            "name": "CUSTOM_ROLE1",
            "description": "custom role for limited member"
        },
        {
            "id": 10001,
            "name": "announcement role",
            "description": "announcement manager"
        }
    ]
}

Error response

All errors return a 400 HTTP response. The details of each error are included in the message field.

{
  "message": "invalid input",
  "error": true,
  "code": 400100
}

List of error properties

Property nameTypeDescription

message

string

The description of an error.

error

boolean

Indicates an error has occurred.

code

int

Indicates a 400 or 500 HTTP response of an error.