API Documentation

#How to Integrate Using the Beebole API

Beebole has a fully documented API that is free for all users. It can be used to integrate with almost any business tool or to create custom applications. We're continuously surprised and delighted by the creative ways Beebole customers use the API!

Your account's API token, which is used to identify you when you make an API request from another app or system, can be found in the API Token module. The module is available to add to your home screen.

Your API token should be treated like a password and kept secret. If you think your token has been compromised, click "Get a new token" in the API Token module.

To enable or disable API calls to your account, go to the "Enable/Disable API calls" section in the Account module, which can be found on your Settings screen.

The goal of our API is to open the data associated with your account and give you the possibility to integrate with or to build custom applications (time entry gadget, reports, etc.). The API provides a full set of services allowing you to create, update, list, and delete time entries in your timesheet.

If you have any questions, please contact our support team.

#Authentication

To enable the API, go to your account, and click "Settings" in the top right menu.

1. Locate the Account module.

2. Click the line labeled "Enable/Disable API calls".

3. Tick the box to enable the API for your account, as shown below:

Here each user will find their respective token in the API Token module. From there you can also reset the token and get a new one.

For every API request, you’ll need to present this token using basic HTTP authentication. You will use the token in the username field of the HTTP authorization header. The password field will always be “x”.

Here is how you will define your authorization’s HTTP header:

1. a username:password pair:

2. base64 encode it:

3. And here is your HTTP authorization header:

#Limits

To prevent errors and abuses, we limit the API access by user, in terms of:

• transfer volume: 2048KB/day

• and number of requests: 4000 requests/day

If you reach this limit, feel free to contact us.

#Request

Beebole accepts HTTP POST requests in a json-doc format to the following URL:

https://beebole-apps.com/api/v2

Do not forget to include "https," as all Beebole API communication with the server will be encrypted.

Data should be UTF-8 encoded.
Date and time values use the format YYYY-MM-DD HH:MM:SS.

Note: In order to quickly test the API calls, we encourage you to install and use cURL. Here is the curl command corresponding to the code portion above:

#Response

All HTTP responses with code 200 will return a “status” node with the value “ok” or “error”. Along with an error status, you will always find a “message” node containing an explanation of what the error is. All the other HTTP codes can be considered to be other error types.

Examples

Request to the server:

Response from the server:

#External ids

In order to integrate Beebole with an existing solution, it’s possible to set the entity ids manually. If the id’s are coming from a system other than Beebole:

• Send xid along with each send create request (example 1)

• Then replace id with xid in all requests and responses (example 2)

#Examples

Example 1: Create request to the server

Response:

Example 2: Get request to the server

Response:

#Absence

#Create an Absence Type

Request:

Response:

#Get an Absence Type

Request:

Response:

#Update an Absence Type

Request:

Response:

#List Absence Types

Request:

Response:

#Activate an Absence Type

Request:

Response:

#Deactivate an Absence Type

Request:

Response:

#Assign a Group to an Absence Type

Request:

Response:

#Unassign a Group to an Absence Type

Request:

Response:

#List Groups Assigned to an Absence Type

Request:

Response:

#Company

#Create a Company

Request:

Response:

#Get a Company

Request:

Response:

#Update a Company

Request:

Response:

#List Companies

Request:

Response:

#Activate a Company

Request:

Response:

#Deactivate a Company

Request:

Response:

#Assign a Specific Task to a Company

Request:

Response:

#Unassign a Specific Task to a Company

Request:

Response:

#List Specific Tasks Assigned to a Company

Request:

Response:

#Enable Specific Tasks for a Company (enabled by default)

Request:

Response:

#Disable Specific Tasks for a Company

Request:

Response:

#Assign an Exclusive Member to a Company

Request:

Response:

#Unassign an Exclusive Member to a Company

Request:

Response:

#List Exclusive Members Assigned to a Company

Request:

Response:

#Assign a Group to a Company

Request:

Response:

#Unassign a Group to a Company

Request:

Response:

#List Groups Assigned to a Company

Request:

Response:

#Set a Custom Field Value to a Company

Request:

Response:

#Clear a Company Custom Field Value

Request:

Response:

#List Custom Fields Assigned to a Company

Request:

Response:

#Person

#Create a Person

Request:

Response:

#Get a Person

Request:

Response:

#Update a Person

Request:

Response:

#List Persons

Request:

Response:

#List Team Leaders of a Person

Request:

Response:

#Activate a Person

Request:

Response:

#Deactivate a Person

Request:

Response:

#Assign a Group to a Person

Request:

Response:

#Unassign a Group to a Person

Request:

Response:

#List Groups Assigned to a Person

Request:

Response:

#Set a Custom Field Value to a Person

Request:

Response:

#Clear a Person Custom Field Value

Request:

Response:

#List Custom Fields Assigned to a Person

Request:

Response:

#Project

#Create a Project

Request:

Response:

#Get a Project

Request:

Response:

#Update a Project

Request:

Response:

#List Projects

Request:

Response:

#Activate a Project

Request:

Response:

#Deactivate a Project

Request:

Response:

#Assign a Specific Task to a Project

Request:

Response:

#Unassign a Specific Task to a Project

Request:

Response:

#List Specific Tasks Assigned to a Project

Request:

Response:

#Enable Specific Tasks for a Project (enabled by default)

Request:

Response:

#Disable Specific Tasks for a Project

Request:

Response:

#Assign an Exclusive Member to a Project

Request:

Response:

#Unassign an Exclusive Member to a Project

Request:

Response:

#List Exclusive Members Assigned to a Project

Request:

Response:

#Assign a Project Manager to a Project

Request:

Response:

#Unassign a Project Manager to a Project

Request:

Response:

#List Project Managers Assigned to a Project

Request:

Response:

#Assign a Group to a Project

Request:

Response:

#Unassign a Group to a Project

Request:

Response:

#List Groups Assigned to a Project

Request:

Response:

#Set a Custom Field Value to a Project

Request:

Response:

#Clear a Project Custom Field Value

Request:

Response:

#List Custom Fields Assigned to a Project

Request:

Response:

#Subproject

#Create a Subproject

Request:

Response:

#Get a Subproject

Request:

Response:

#Update a Subproject

Request:

Response:

#List Subprojects

Request:

Response:

#Activate a Subproject

Request:

Response:

#Deactivate a Subproject

Request:

Response:

#Assign a Specific Task to a Subproject

Request:

Response:

#Unassign a Specific Task to a Subproject

Request:

Response:

#List Specific Tasks Assigned to a Subproject

Request:

Response:

#Enable Specific Tasks for a Subproject (enabled by default)

Request:

Response:

#Disable Specific Tasks for a Subproject

Request:

Response:

#Assign an Exclusive Member to a Subproject

Request:

Response:

#Unassign an Exclusive Member to a Subproject

Request:

Response:

#List Exclusive Members Assigned to a Subproject

Request:

Response:

#Assign a Group to a Subproject

Request:

Response:

#Unassign a Group to a Subproject

Request:

Response:

#List Groups Assigned to a Subproject

Request:

Response:

#Set a Custom Field Value to a Subproject

Request:

Response:

#Clear a Subproject Custom Field Value

Request:

Response:

#List Custom Fields Assigned to a Subproject

Request:

Response:

#Task

#Create a Task

Request:

Response:

#Get a Task

Request:

Response:

#Update a Task

Request:

Response:

#List Tasks

Request:

Response:

#Activate a Task

Request:

Response:

#Deactivate a Task

Request:

Response:

#Assign a Group to a Task

Request:

Response:

#Unassign a Group to a Task

Request:

Response:

#List Groups Assigned to a Task

Request:

Response:

#Group

#Create a Group

Request:

Response:

#Get a Group

Request:

Response:

#Update a Group

Request:

Response:

#Delete a Group

Request:

Response:

#List Groups Assigned to an Entity

Request:

Response:

#List Entities Assigned to a Group

Request:

Response:

#Groups Tree

Request:

Response:

#Custom Field

#List Custom Fields

Request:

Response:

#Time

This section deals with the management of timesheet entries.

We will call “entity” a company, project, subproject, task, or absence.

In order to log hours on an entity you should follow those simple rules:

• You can log time on a combination of a company, a project, or a subproject with a task if any (mandatory), or on an absence.

• You can only log hours on the leaves of the following hierarchical structure:

  • company

    • project

      • subproject

#Examples:

If a company has projects and the project you choose has subprojects and, moreover, general tasks are defined, you will enter the create/update service with the following parameters:

without tasks:

if a company has only projects:

if the company doesn’t have any projects:

if you log hours on an absence (tasks don’t matter in this case):

In summary, you get the entity ids and hierarchy with the service get_entities, you get the tasks associated, if any, using the get_tasks service, and you create or update a time entry following the rules mentioned.

In the case of trying to log hours on inappropriate entities, you will receive an error message.

#Get Entities to Create a Time Entry

Request:

Response:

We want to log hours on the “Dev” project, which has subprojects. So, again, we call time_entry.get_entities but this time mentioning the project id (think of expanding a tree branch):

Request:

Response:

We pick the “Analyse” subproject and, in order to know if any task is available for this entity, we use the following service with the subproject id:

#Get Tasks to Create a Time Entry

Request:

Response:

We have now collected all the necessary information in order to fill in the create/update service request.

#Create a Time Entry

Request:

Response:

#Update a Time Entry

Request:

Response:

#Get a Time Entry

Request:

Response:

#Delete a Time Entry

Request:

Response:

#List Time Entries

Request:

Response:

#Submit Time Entry

Request:

Response:

#Approve Time Entry

Request:

Response:

#Reject Time Entry

Request:

Response:

#Lock Time Entry

Request:

Response:

#Unlock Time Entry

Request:

Response:

#Time Export

This section deals with the retrieval of timesheet entries.

The API uses the following two services in order to retrieve time records:

• The service time_entry.export initiates and launches an export job. This job is queued and processed in the background. The service’s response will be a new job object. The job object is composed of a unique ID, its status, and, if it has been completed, a result.

• If the previous service doesn't respond with a result, the service time_entry.get_job_info will be used to query the job status and get the final result. As for the export service, it will return a job object.

How to use those services:

1. call the service time_entry.export to initiate a new export job and receive a new job ID.

2. call the service time_entry.get_job_info periodically (every 5 sec) in order to check if the job has been done and if the response contains a result. You should exit the loop on a service status or a job.status == “error”, or when the job.status == “done” and job.result is of type string.

#Export Time Entries

This service initiates a new export job. This job is queued and processed in the background.

The service wraps the in app export module functionality.

Parameters:

• “from" and "to”

• “show” and “keys”: these two parameters are linked. The “show” parameter represents what kind of report you want to get. Depending on the “show” parameter, you will adapt the “keys” parameter, which represents the columns you want to export.

• “statusFilters”: this represents the time record filter.

[d]raft, [s]ubmitted, [a]pproved, [r]ejected, [l]ocked

• “gids”: this represents the groups filter, and array of integer group IDs.

• “outputFormat”: “array”: this parameter is optional. It allows you to export the result as an array of arrays instead of CSV.

Request:

Response:

#Get Job Info

Request:

Response:

OR if it’s done

Response: