DeskBee API (1.1)

Deskbee provides a REST API so you can integrate or automate actions.

The communication base address is api.deskbee.io, always accompanied by the secure protocol https://. API versions are grouped by directory, suffixed to base address (https://api.deskbee.io/v1.1).

📢 We can provide an environment for internal testing and development tests. Just contact help@deskbee.co

The API supports two methods for sending parameters

QueryString

curl --request POST 'https://api.deskbee.io/v1.1/oauth/token' \
--data-raw 'grant_type=client_credentials&client_id=942ff....e4e23676e'

JSON

curl --request POST 'https://api.deskbee.io/v1.1/oauth/token' \
--header   'Content-Type: application/json' \
--data-raw '{
    "grant_type" : "client_credentials",
    "client_id' :"",
    "client_secret' : "",
    "scope" : ""
}'

Some requests made in the API will return a list of information, this information will not be returned in a single response, this is because some responses may have a lot of information, so these requests are paginated.

The Deskbee API uses paging by cursor, in this paging a key parameter is used.

The client receives a variable named cursor along with the response. This cursor is a pointer that points to a specific item that needs to be sent with a request. The server then uses the cursor to fetch the other set of items.

Cursor-based paging is more complex and is preferred when dealing with a real-time dataset.

Below is an example of a cursor-paged JSON response:

Request / Response

Description of the parameters that can be sent in the Deskbee API pagination

curl -i -X GET 'https://api.deskbee.io/v1.1/users?limit=1' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>'

Description of the parameters received in the Deskbee API pagination

{
  "data": [{
    ...
  }, {
    ...
  }, {
    ...
  }],
  "links": {
    "prev": "https://api.deskbee.io/v1.1/users?cursor=eyJuYW1lIjoiS3VyaXJpbiIsIl9wb2ludHNUb05leHRJdGVtcyI6ZmFsc2V9",
    "next": "https://api.deskbee.io/v1.1/users?cursor=eyJuYW1lIjoiS3VyaXJpbiIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"
  },
  "meta": {
    "path": "https://api.deskbee.io/v1.1/users",
    "per_page": "2"
  }
}

All responses are returned in valid JSON format.

Dates are returned in ISO8601 format.

{
  // ...
  "created_at": "2020-01-01T12:00:00Z",
  "updated_at": "2020-01-01T13:00:00Z",
  // ...
}

Each response returns an appropriate HTTP code as specified https://datatracker.ietf.org/doc/html/rfc7231#section-6

Successful Returns

{
    "data": {
        "uuid": "68b0327b-e0f9-40e2-a81c-15fb0d981ede",
        "name": "Grupo Teste",
        "is_checkin_home_office": false,
        "created_at": "2021-09-23T14:28:36-03:00",
        "updated_at": "2021-09-23T14:28:36-03:00"
    }
}

Error Returns

In the event of returning an error, HTTP Status Code different from 2xx for example, a structured and consistent error will be generated in the body of the response.

{
  "error": 422
  "id": "unprocessable_entity",
  "message": "The given data failed to pass validation.",
  "errors": {
    "email": ["The email field is required."],
    "name": ["The name field is required."]
  }
}

Errors returned by the Deskbee API

To begin integration with Deskbee's API, it is necessary to create a ClientApi in the Deskbee Panel.

📢 Only users with Admin and Master Profile permissions have access to the integrations menu

1. Access the Deskbee Panel, Integrations > ClientApi and click on New Client
2. Enter a name that will be used to identify the application and choose what it will have access to.
3. After successfully creating the application, click on the data visualization icon.
4. The Client ID, Client Secret and Scopes will be displayed. These are the 3 pieces of data needed to create an Authentication Token (OAuth2).

📢 ATTENTION

For compliance, choose only the scopes that the application needs to use

Authentication

Everything about your Buildings

Everything about your Floors

Everything about your parkings

Places

Returns data from cost centers

Returns data from users

Returns data from squads