This site uses cookies. By continuing to browse the site you are agreeing to our use of cookies.  Find out more here Ok

API Documentation


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, …). 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 support@beebole.com


Authentication

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

Then locate the module: Account.

Click the line labelled: Enable/Disable API calls.

And tick the box to enable the API for your account, as below:

account

Then, each user will find their respective token in the ‘API Token’ module. From there it will be also possible to reset it and get a new one:

api_key

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:

"803b433162432915ce2e7b25a022910925ab73c2:x"

2) base64 encode it:

"ODAzYjQzMzE2MjQzMjkxNWNlMmU3YjI1YTAyMjkxMDkyNWFiNzNjMjp4"

3) … and here is your HTTP authorization header:

"Authorization: Basic ODAzYjQzMzE2MjQzMjkxNWNlMmU3YjI1YTAyMjkxMDkyNWFiNzNjMjp4"

Limits

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

  • transfer volume: 2048KB/day
  • and number of requests: 4000 requests/day

If you reach this limit feel free to contact us at support@beebole.com.

Request

BeeBole is accepting HTTP POST resquests in a JSON format to the following URL:

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

Don’t forget the https as all the BeeBole API communication with the server will be encrypted.

Data should be UTF-8 encoded.
Date and time values are of the form YYYY-MM-DD HH:MM:SS.

1  {
2  "service": "absence.list",
3  "company" : {"id" : 233}
4  }

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:

curl -k -X POST https://803b433162432915ce2e7b25a022910925ab73c2:x@yourClientAlias.beebole-apps.com/api/v2 -d "{\"service\":\"company.list\"}"

Response

Each response 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.

Examples

→ request to the server

1  {
2    "status": "ok",
3    "absences": [
4      // ...
5    ]
6  }

← response from the server

1  {
2    "status": "error",
3    "message": "Invalid service request ..."
4  }

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 another system 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

1{
2  "service" : "company.create",
3  "company" : {
4    "xid" : "56478",
5    "name" : "myCompany"
6  }
7}

← response

1{
2  "status" : "ok",
3  "xid" : "56478"
4}

→ Example 2 : get request to the server

1{
2  "service" : "company.get",
3  "xid" : "56478"
4}

← response

 1{
 2  "status" : "ok",
 3  "company" : {
 4    "xid" : "56478",
 5    "name" : "myCompany",
 6    "active" : true,
 7    "projects": {
 8      "count" : 3
 9    }
10  }
11}

Absence

absence.create

1{
2  "service": "absence.create",
3  "absence": {
4    "name": "myAbsence",
5    "company": {"id": 233}
6  }
7}

1{
2  "status": "ok",
3  "id": 78
4}

absence.get

1{
2  "service": "absence.get",
3  "id": 78
4}

 1{
 2  "status" : "ok",
 3  "absence" : {
 4    "id" : 78,
 5    "name" : "myAbsence",
 6    "company" : {"id" : 233},
 7    "active" : true
 8  }
 9}

absence.update

1{
2  "service" : "absence.update",
3  "absence" : {
4    "id" : 78,
5    "name" : "newName"
6  }
7}

1{"status" : "ok"}

absence.list

1{
2  "service": "absence.list",
3  "company" : {"id" : 233}
4}

 1{
 2  "status" : "ok",
 3  "absences": [
 4    {
 5      "id" : 78,
 6      "name" : "myAbsence",
 7      "company": {id : 233},
 8      "active" : true
 9    }, ...
10  ]
11}

absence.activate

1{
2  "service": "absence.activate",
3  "id": 78
4}

1{"status": "ok"}

absence.deactivate

1{
2  "service": "absence.deactivate",
3  "id": 78
4}

1{"status": "ok"}

Company

company.create

1{
2  "service": "company.create",
3  "company": {
4    "name": "myCompany"
5  }
6}

1{
2  "status": "ok",
3  "id": 233
4}

company.get

1{
2  "service": "company.get",
3  "id": 233
4}

 1{
 2  "status" : "ok",
 3  "company" : {
 4    "id" : 233,
 5    "name" : "myCompany",
 6    "projects": {
 7      "count": 3
 8    },
 9    "active" : true
10  }
11}

company.update

1{
2  "service" : "company.update",
3  "company" : {
4    "id" : 233,
5    "name" : "newName"
6  }
7}

1{"status" : "ok"}

company.list

1{
2  "service": "company.list"
3}

 1{
 2  "status" : "ok",
 3  "companies": [
 4    {
 5      "id" : 233,
 6      "name" : "myCompany",
 7      "projects": {"count": 3},
 8      "active" : true
 9    }, ...
10  ]
11}

company.activate

1{
2  "service": "company.activate",
3  "id": 233
4}

1{"status": "ok"}

company.deactivate

1{
2  "service": "company.deactivate",
3  "id": 233
4}

1{"status": "ok"}

company.attach_specific_task

1{
2  "service" : "company.attach_specific_task",
3  "id" : 78,
4  "task" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

company.detach_specific_task

1{
2  "service" : "company.detach_specific_task",
3  "id" : 78,
4  "task" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

company.specific_tasks

1{
2  "service" : "company.specific_tasks",
3  "id" : 78
4}

 1{
 2 "status" : "ok",
 3 "specificTasks": [
 4   {
 5     "name" : "Administration",
 6     "id" : 345
 7   }, ...
 8 ]
 9}

company.attach_member

1{
2  "service" : "company.attach_member",
3  "id" : 78,
4  "person" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

company.detach_member

1{
2  "service" : "company.detach_member",
3  "id" : 78,
4  "person" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

company.members

1{
2  "service" : "company.members",
3  "id" : 78
4}

 1{
 2 "status" : "ok",
 3 "members": [
 4   {
 5     "name" : "John Le Carré",
 6     "id" : 345
 7   }, ...
 8 ]
 9}

Person

person.create

1{
2  "service": "person.create",
3  "person": {
4    "name": "Rosa Parks",
5    "company": {"id": 233}
6  }
7}

1{
2  "status": "ok",
3  "id": 455
4}

person.get

1{
2  "service": "person.get",
3  "id": 455
4}

 1{
 2  "status" : "ok",
 3  "person" : {
 4    "id" : 455,
 5    "name" : "Rosa Parks",
 6    "company" : {"id" : 233},
 7    "active" : true
 8  }
 9}

person.update

1{
2  "service" : "person.update",
3  "absence" : {
4    "id" : 455,
5    "name" : "newName"
6  }
7}

1{"status" : "ok"}

person.list

1{
2  "service": "person.list",
3  "company" : {"id" : 233}
4}

 1{
 2  "status": "ok",
 3  "people": [
 4    {
 5      "id": 455,
 6      "name" : "Rosa Parks",
 7      "company": {id : 233},
 8      "active" : true
 9    }, ...
10  ]
11}

person.activate

1{
2  "service": "person.activate",
3  "id": 455
4}

1{"status": "ok"}

person.deactivate

1{
2  "service": "person.deactivate",
3  "id": 455
4}

1{"status": "ok"}

Project

project.create

 1{
 2  "service": "project.create",
 3  "project": {
 4    "name": "Development",
 5    "startDate": "2014-10-13", //optional, default 1st current month
 6    "description" : "some description ...", //optional
 7    "company": {"id": 233}
 8  }
 9}

1{
2  "status": "ok",
3  "id": 321
4}

project.get

1{
2  "service": "project.get",
3  "id": 321
4}

 1{
 2  "status" : "ok",
 3  "project" : {
 4    "id" : 321,
 5    "name" : "Development",
 6    "startDate": "2014-10-13",
 7    "description" : "some description ...",
 8    "company" : {"id" : 233},
 9    "subprojects" : {"count" : 2},
10    "active" : true
11  }
12}

project.update

1{
2  "service" : "project.update",
3  "project" : {
4    "id" : 321,
5    "name" : "newName"
6  }
7}

1{"status" : "ok"}

project.list

1{
2  "service": "project.list",
3  "company" : {"id" : 233}
4}

 1{
 2  "status": "ok",
 3  "projects": [
 4    {
 5      "id": 321,
 6      "name" : "Development",
 7      "startDate": "2014-10-13",
 8      "description" : "some description ...",
 9      "company": {id : 233},
10      "subprojects" : {"count" : 2},
11      "active" : true
12    }, ...
13  ]
14}

project.activate

1{
2  "service": "project.activate",
3  "id": 321
4}

1{"status": "ok"}

project.deactivate

1{
2  "service": "project.deactivate",
3  "id": 321
4}

1{"status": "ok"}

project.attach_specific_task

1{
2  "service" : "project.attach_specific_task",
3  "id" : 78,
4  "task" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

project.detach_specific_task

1{
2  "service" : "project.detach_specific_task",
3  "id" : 78,
4  "task" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

project.specific_tasks

1{
2  "service" : "project.specific_tasks",
3  "id" : 78
4}

 1{
 2 "status" : "ok",
 3 "specificTasks": [
 4   {
 5     "name" : "Administration",
 6     "id" : 345
 7   }, ...
 8 ]
 9}

project.attach_member

1{
2  "service" : "project.attach_member",
3  "id" : 78,
4  "person" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

project.detach_member

1{
2  "service" : "project.detach_member",
3  "id" : 78,
4  "person" : {
5    "id" : 43
6  }
7}

1{"status" : "ok"}

project.members

1{
2  "service" : "project.members",
3  "id" : 78
4}

 1{
 2 "status" : "ok",
 3 "members": [
 4   {
 5     "name" : "John Le Carré",
 6     "id" : 345
 7   }, ...
 8 ]
 9}

Subproject

subproject.create

1{
2  "service": "subproject.create",
3  "subproject": {
4    "name": "Prototype",
5    "project": {"id": 321}
6  }
7}

1{
2  "status": "ok",
3  "id": 765
4}

subproject.get

1{
2  "service": "subproject.get",
3  "id": 765
4}

 1{
 2  "status" : "ok",
 3  "subproject" : {
 4    "id" : 765,
 5    "name" : "Prototype",
 6    "project" : {"id" : 765},
 7    "active" : true
 8  }
 9}

subproject.update

1{
2  "service" : "subproject.update",
3  "subproject" : {
4    "id" : 765,
5    "name" : "newName"
6  }
7}

1{"status" : "ok"}

subproject.list

1{
2  "service": "subproject.list",
3  "project" : {"id" : 765}
4}

 1{
 2  "status": "ok",
 3  "subprojects": [
 4    {
 5      "id" : 765,
 6      "name" : "Prototype",
 7      "project" : {"id" : 765},
 8      "active" : true
 9    }, ...
10  ]
11}

subproject.activate

1{
2  "service": "subproject.activate",
3  "id": 765
4}

1{"status": "ok"}

subproject.deactivate

1{
2  "service": "subproject.deactivate",
3  "id": 765
4}

1{"status": "ok"}

Task

task.create

1{
2  "service": "task.create",
3  "task": {
4    "name": "Meeting",
5    "company": {"id": 233}
6  }
7}

1{
2  "status": "ok",
3  "id": 955
4}

task.get

1{
2  "service": "task.get",
3  "id": 955
4}

 1{
 2  "status" : "ok",
 3  "task" : {
 4    "id" : 955,
 5    "name" : "Meeting",
 6    "company" : {"id" : 233},
 7    "active" : true
 8  }
 9}

task.update

1{
2  "service" : "task.update",
3  "task" : {
4    "id" : 955,
5    "name" : "newName"
6  }
7}

1{"status" : "ok"}

task.list

1{
2  "service": "task.list",
3  "company" : {"id" : 233}
4}

†←

 1{
 2  "status": "ok",
 3  "tasks": [
 4    {
 5      "id" : 955,
 6      "name" : "Meeting",
 7      "company" : {"id" : 233},
 8      "active" : true
 9    }, ...
10  ]
11}

task.activate

1{
2  "service": "task.activate",
3  "id": 955
4}

1{"status": "ok"}

task.deactivate

1{
2  "service": "task.deactivate",
3  "id": 955
4}

1{"status": "ok"}

Time

This section deals with the timesheet entries management.

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

In order to log hours on an entity you will 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
        • sub project

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:

suproject.id
task.id

without tasks:

subproject.id

if a company has only projects:

project.id
task.id

if the company doesn’t have any projects:

company.id
task.id

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

absence.id

To sum up, 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 case of you try to log hours on inappropriate entities, you will receive an error message.

time_entry.get_entities

1{
2  "service": "time_entry.get_entities",
3  "company": {
4    "id": 3
5  },
6  "date": "2014-06-16"
7}

 1{
 2  "projects":[
 3    {
 4      "id":30,
 5      "name":"Dev",
 6      "active":true,
 7      "subprojects":{"count":2}
 8    },
 9    {
10      "id":4131,
11      "name":"Marketing",
12      "active":true,
13      "subprojects":{"count":0}
14    },
15    {
16      "id":4128,
17      "name":"Sales",
18      "active":true,
19      "subprojects":{"count":0}
20    }
21  ]
22}

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

1{
2  "service": "time_entry.get_entities",
3  "project": {
4    "id": 30
5  },
6  "date": "2014-06-16"
7}

 1{
 2  "subprojects":[
 3    {
 4      "active":true,
 5      "name":"Analyse",
 6      "id":37
 7    },
 8    {
 9      "active":true,
10      "name":"Proto",
11      "id":31
12    }
13  ]
14}

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 :

time_entry.get_tasks

1{
2  "service": "time_entry.get_tasks",
3  "subproject": {
4    "id": 37
5  },
6  "date": "2014-07-16"
7}

 1{
 2  "tasks":[
 3    {
 4      "active":true,
 5      "name":"Administration",
 6      "id":17
 7    },
 8    {
 9      "active":true,
10      "name":"Meetings",
11      "id":18
12    },
13    {
14      "active":true,
15      "name":"Research",
16      "id":19
17    }
18  ]
19}

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

time_entry.create

 1{
 2  "service": "time_entry.create",
 3  "subproject": {
 4    "id": 37
 5  },  //company.id, project.id, subproject.id or absence.id
 6  "task":{
 7    "id": 17
 8  },  //mandatory if any
 9  "date": "2014-08-05",
10  "hours": 8,
11  "comment": "some comment"
12}

 1{
 2  "status":"ok",
 3  "timeEntry":{
 4    "hours":8.0,
 5    "status":"d",
 6    "subproject":{
 7      "id":37,
 8      "name":"Analyse"
 9    },
10    "task":{
11      "name":"Administration",
12      "id":17
13    },
14    "id":500901,
15    "date":"2014-09-29",
16    "comment":"some comment"
17  }
18}

time_entry.update

 1{
 2  "service": "time_entry.update",
 3  "id":500901,
 4  "subproject":{
 5    "id": 37
 6  },//company.id, project.id, subproject.id or absence.id
 7  "task":{
 8    "id": 17
 9  },//mandatory if there are tasks defined, and not an absence
10  "date": "2014-09-29",
11  "hours": 7,
12  "comment": "updated comment"
13}

 1{
 2  "status":"ok",
 3  "timeEntry":{
 4    "hours":7.0,
 5    "status":"d",
 6    "subproject":{
 7      "id":37,
 8      "name":"Analyse"
 9    },
10    "task":{
11      "name":"Administration",
12      "id":17
13    },
14    "id":500901,
15    "date":"2014-09-29",
16    "comment":"updated comment"
17  }
18}

time_entry.get

1{
2  "service": "time_entry.get",
3  "id": "500901",
4  "date":"2014-09-29"
5}

 1{
 2 "status":"ok",
 3 "timeEntry":{
 4     "hours":7.0,
 5     "status":"d",
 6     "subproject":{
 7       "id":37,
 8       "name":"Analyse"
 9     },
10     "task":{
11       "name":"Administration",
12       "id":17
13     },
14     "id":500901,
15     "date":"2014-09-29",
16     "comment":"updated comment"
17   }
18}

time_entry.list

1{
2 "service": "time_entry.list",
3 "person" : {
4   "id": 2
5 },
6 "from": "2014-09-01",
7 "to": "2014-09-30"
8}

 1{
 2 "status":"ok",
 3 "timeEntries":[
 4   {
 5     "hours":7.0,
 6     "status":"d",
 7     "subproject":{
 8       "id":37,
 9       "name":"Analyse"
10     },
11     "task":{
12       "name":"Administration",
13       "id":17
14     },
15     "id":500901,
16     "date":"2014-09-29",
17     "comment":"updated comment"
18   },
19   ...
20 ]
21}

Time Export

This section deals with the timesheet entries retrieval.

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

  • The service time_entry.export initiates and launch an export job. This job is queued and is processed in the background. The service’s response will be a new job object. The job object is composed with a unique ID, its status and, if it has been completed, a result.
  • If the previous service didn’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 (each 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.

time_entry.export

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” : each call is limited to a time range of one month (up to 31 days).

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

show/keys abs (Absence) all (Working Time & Absence) quota (Absence Quotas) work (Working Time)
company x x x x
companyId x x x x
person x x x x
personId x x x x
project x x   x
projectId x x   x
subproject x x   x
subprojectId x x   x
absence x x x x
absenceId x x x x
task x x   x
taskId x x   x
hours x x   x
date x x   x
inDays x x x x
billing x x   x
cost x x   x
status x x   x
hourlyRate x x   x
dailyRate x x   x
available     x  
balance     x  
taken     x  
fromTo     x  
month x x   x

“statusFilters” : this represents the time record filter.

status description
a approved
d draft
l locked
r rejected
s submitted

1{
2  "service": "time_entry.export",
3  "from": "2013-10-01",
4  "to" : "2013-10-30",
5  "show" : "all", // Optional default "all"
6  "keys" : ["company", "companyId", "hours"],
7  "statusFilters" : ["l", "a"] // optional
8}

1{
2  "status":"ok",
3  "job": {
4    "status":"running",
5    "id":1148
6  }
7}

time_entry.get_job_info

1{
2  "service":"time_entry.get_job_info",
3  "id":1148
4}

1{
2  "status":"ok",
3  "job": {
4    "status":"running",
5    "id":1148
6  }
7}

OR if it’s done

1{
2  "status":"ok",
3  "job": {
4    "status":"done",
5    "id":1148,
6    "result":"Entreprise,Heures\nBranch,\"7,000\"\nMyCompany,\"63,000\"\n ..."
7  }
8}

No credit card required Try it Free for 30 Days Questions? Send us an email