API Documentation
Read data from BeeBole or write data to BeeBole
Introduction
Welcome to the BeeBole API documentation.
The goal of the 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.
Table of Contents
If you have any question or problem, please contact us
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:
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:
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: 1024KB/day
- and number of requests: 2000 requests/day
If you reach this limit feel free to contact us
Back to topRequest
BeeBole is accepting HTTP POST resquests in a JSON format to the following URL:
https://yourAccount.beebole-apps.com/api
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.
Each request will be composed of a "service" node and the rest of parameters.
Example:
→
1 2 3 4
{
"service": "absence.list",
"company_id": 3
}
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 -d '{"service":"absence.list", "company_id":3}'
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 3 4
{
"status": "ok",
"absences": [ ... ]
}
← response from the server
1 2 3 4
{
"status": "error",
"message": "Invalid service request ..."
}
Back to top
Absence
absence.list
→
1 2 3 4
{
"service": "absence.list",
"company_id": 3
}
←
1 2 3 4 5 6 7 8
{
"status":"ok",
"absences":[
{"id":17,"name":"Sickness"},
{"id":16,"name":"Leave"},
{"id":15,"name":"Holidays"}
]
}
Back to top
Company
company.list
→
1 2 3
{
"service": "company.list"
}
←
1 2 3 4 5 6 7
{
"status":"ok",
"companies":[
{"id":3,"name":"BeeBole"},
{"id":23,"name":"Electracom"}
]
}
Back to top
Person
person.list
→
1 2 3 4
{
"service": "person.list",
"company_id": 3 //optional
}
←
1 2 3 4 5 6 7
{
"status":"ok",
"people":[
{"id":21,"name":"Michael Cvilic"},
{"id":2,"name":"Hughes Waroquier"}
]
}
Back to top
Project
project.list
→
1 2 3 4
{
"service": "project.list",
"company_id": 3 //optional
}
←
1 2 3 4 5 6 7
{
"status":"ok",
"projects":[
{"id":19,"name":"Admin"},
{"id":18,"name":"Dev"}
]
}
Back to top
Subproject
subproject.list
→
1 2 3 4
{
"service": "subproject.list",
"project_id": 18
}
←
1 2 3 4 5 6
{
"subprojects":[
{"id":25,"name":"Prototype"},
{"id":24,"name":"API"}
]
}
Task
task.list
→
1 2 3 4
{
"service": "task.list",
"company_id": 3
}
←
1 2 3 4 5 6
{
"status":"ok",
"tasks":[
{"id":29,"name":"Code"}
]
}
Back to top
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 :
companyprojectsub 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 (if any)
task_id
if the company doesn't have any projects:
company_id (if any)
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 and 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 along with a list of entities(children) proposal.
time.create
→
1 2 3 4 5 6 7 8
{
"service": "time_entry.create",
"subproject_id": 25, //company_id, project_id, subproject_id or absence_id
"task_id": 29,
"date": "2011-01-05",
"hours": 8,
"notes": "some comment"
}
←
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
{
"status":"ok",
"timeEntry":{
"hours":8.0,
"status":"d",
"subproject":{
"id":25,
"name":"Prototype"
},
"task":{
"name":"Code",
"id":29
},
"id":16,
"date":"2011-01-06",
"notes":"some comment"
}
}
time.get
→
1 2 3 4
{
"service": "time_entry.list"
"id": 16
}
←
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
{
"status":"ok",
"timeEntry":{
"hours":7.0,
"status":"d",
"subproject":{
"id":25,
"name":"Prototype"
},
"task":{
"name":"Code",
"id":29
},
"id":16,
"date":"2011-01-06",
"notes":"another comment"
}
}
time.get_entities
→
1 2 3 4 5
{
"service": "time_entry.get_entities"
"person_id": 21 // optional
"format": "tree" // optional, "tree"(default) or "flat"
}
←
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29
{
"status":"ok",
"companies":[
{
"name":"BeeBole",
"id":3,
"projects":[
{
"name":"Dev",
"id":18,
"subprojects":[
{"id":25,"name":"Prototype"},
{"id":24,"name":"API"}
]
},
{"id":19,"name":"Admin"}
]
},
...
],
"absences":[
{"id":15,"name":"Holidays"},
{"id":16,"name":"Leave"},
{"id":17,"name":"Sickness"}
],
"tasks":[
{"id":29,"name":"Code"}
]
}
← Flat
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33
{
"status":"ok",
"entities":[
{
"subproject":{
"name":"Prototype",
"id":25,
"parents":[
{
"company":{
"id":3,
"name":"BeeBole"
}
},
{
"project:{
"id":18,
"name":"Dev"
}
}
]
},
...
],
"absences":[
{"id":15,"name":"Holidays"},
{"id":16,"name":"Leave"},
{"id":17,"name":"Sickness"}
],
"tasks":[
{"task_id":29,"task_name":"Code"}
]
}
time.list
→
1 2 3 4 5 6
{
"service": "time_entry.list"
"person_id": 21 //optional
"from": "2011-01-03",
"to": "2011-01-09"
}
←
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{
"status":"ok",
"timeEntries":[
{
"hours":7.0,
"status":"d",
"subproject":{
"id":25,
"name":"Prototype"
},
"task":{
"name":"Code",
"id":29
},
"id":16,
"date":"2011-01-06",
"notes":"another comment"
},
...
]
}
time.update
→
1 2 3 4 5 6 7 8 9
{
"service": "time_entry.update"
"id":16,
"subproject_id": 25, //company_id, project_id, subproject_id or absence_id
"task_id": 29, //mandatory if existing and not absence_id
"date": "2011-01-05",
"hours": 7,
"notes": "another comment"
}
←
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
{
"status":"ok",
"timeEntry":{
"hours":7.0,
"status":"d",
"subproject":{
"id":25,
"name":"Prototype"
},
"task":{
"name":"Code",
"id":29
},
"id":16,
"date":"2011-01-05",
"notes":"another comment"
}
}
Back to top