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.

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.

Locate the Account module.
Click the line labeled "Enable/Disable API calls".
Tick the box to enable the API for your account, as shown below:

Account settings for the API

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.

API token self

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

  {
  "service": "absence.list",
  "company" : {"id" : 233}
  }

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@beebole-apps.com/api/v2
-d "{\"service\":\"company.list\"}"

#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:

  {
    "status": "ok",
    "absences": [
      // ...
    ]
  }

Response from the server:

  {
    "status": "error",
    "message": "Invalid service request ..."
  }

#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

{
  "service" : "company.create",
  "company" : {
    "xid" : "56478",
    "name" : "myCompany"
  }
}

Response:

{
  "status" : "ok",
  "xid" : "56478"
}

Example 2: Get request to the server

{
  "service" : "company.get",
  "xid" : "56478"
}

Response:

{
  "status" : "ok",
  "company" : {
    "xid" : "56478",
    "name" : "myCompany",
    "active" : true,
    "projects": {
      "count" : 3
    }
  }
}

#Absence

#Create an Absence Type

Request:

{
  "service": "absence.create",
  "absence": {
    "name": "myAbsence",
    "company": {"id": 233}
  }
}

Response:

{
  "status": "ok",
  "id": 78
}

#Get an Absence Type

Request:

{
  "service": "absence.get",
  "id": 78
}

Response:

{
  "status" : "ok",
  "absence" : {
    "id" : 78,
    "name" : "myAbsence",
    "company" : {"id" : 233},
    "active" : true
  }
}

#Update an Absence Type

Request:

{
  "service" : "absence.update",
  "absence" : {
    "id" : 78,
    "name" : "newName"
  }
}

Response:

{"status" : "ok"}

#List Absence Types

Request:

{
  "service": "absence.list",
  "company" : {"id" : 233}
}

Response:

{
  "status" : "ok",
  "absences": [
    {
      "id" : 78,
      "name" : "myAbsence",
      "company": {"id" : 233},
      "active" : true
    }, ...
  ]
}

#Activate an Absence Type

Request:

{
  "service": "absence.activate",
  "id": 78
}

Response:

{"status": "ok"}

#Deactivate an Absence Type

Request:

{
  "service": "absence.deactivate",
  "id": 78
}

Response:

{"status": "ok"}

#Assign a Group to an Absence Type

Request:

{
  "service" : "absence.add_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#Unassign a Group to an Absence Type

Request:

{
  "service" : "absence.remove_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#List Groups Assigned to an Absence Type

Request:

{
  "service" : "absence.groups",
  "id" : 78
}

Response:

{
  "status":"ok",
  "groups":[
    {
      "id":4787,
      "name":"US",
      "groups":{"count":4}
    }, ...
  ]
}

#Company

#Create a Company

Request:

{
  "service": "company.create",
  "company": {
    "name": "myCompany",
    "corporate" : true      //optional: is the company corporate or customer ?  default false (customer)
  }
}

Response:

{
  "status": "ok",
  "id": 233
}

#Get a Company

Request:

{
  "service": "company.get",
  "id": 233
}

Response:

{
  "status" : "ok",
  "company" : {
    "id" : 233,
    "name" : "myCompany",
    "projects": {
      "count": 3
    },
    "active" : true
  }
}

#Update a Company

Request:

{
  "service" : "company.update",
  "company" : {
    "id" : 233,
    "name" : "newName"
  }
}

Response:

{"status" : "ok"}

#List Companies

Request:

{
  "service": "company.list"
}

Response:

{
  "status" : "ok",
  "companies": [
    {
      "id" : 233,
      "name" : "myCompany",
      "projects": {"count": 3},
      "active" : true
    }, ...
  ]
}

#Activate a Company

Request:

{
  "service": "company.activate",
  "id": 233
}

Response:

{"status": "ok"}

#Deactivate a Company

Request:

{
  "service": "company.deactivate",
  "id": 233
}

Response:

{"status": "ok"}

#Assign a Specific Task to a Company

Request:

{
  "service" : "company.attach_specific_task",
  "id" : 78,
  "task" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#Unassign a Specific Task to a Company

Request:

{
  "service" : "company.detach_specific_task",
  "id" : 78,
  "task" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#List Specific Tasks Assigned to a Company

Request:

{
  "service" : "company.specific_tasks",
  "id" : 78
}

Response:

{
 "status" : "ok",
 "disabled" : false,  //default : false
 "specificTasks": [
   {
     "name" : "Administration",
     "id" : 345,
     "active":true
   }, ...
 ]
}

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

Request:

{
  "service" : "company.enable_specific_tasks",
  "id" : 78
}

Response:

{"status" : "ok"}

#Disable Specific Tasks for a Company

Request:

{
  "service" : "company.disable_specific_tasks",
  "id" : 78
}

Response:

{"status" : "ok"}

#Assign an Exclusive Member to a Company

Request:

{
  "service" : "company.attach_member",
  "id" : 78,
  "person" : {  // "person" or "group"
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#Unassign an Exclusive Member to a Company

Request:

{
  "service" : "company.detach_member",
  "id" : 78,
  "person" : {  // "person" or "group"
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#List Exclusive Members Assigned to a Company

Request:

{
  "service" : "company.members",
  "id" : 78
}

Response:

{
 "status" : "ok",
 "members": [
   {
     "name" : "John Le Carré",
     "id" : 345
   }, ...
 ],
 "groups": [
   {
     "name" : "US",
     "id" : 978
   }, ...
 ]
}

#Assign a Group to a Company

Request:

{
  "service" : "company.add_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#Unassign a Group to a Company

Request:

{
  "service" : "company.remove_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#List Groups Assigned to a Company

Request:

{
  "service" : "company.groups",
  "id" : 78
}

Response:

{
  "status":"ok",
  "groups":[
    {
      "id":4787,
      "name":"US",
      "groups":{"count":4}
    }, ...
  ]
}

#Set a Custom Field Value to a Company

Request:

{
  "service" : "company.set_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 7206,
    "value" : "Transportation"
  }
}

Response:

{"status": "ok"}

#Clear a Company Custom Field Value

Request:

{
  "service" : "company.clear_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 7206
  }
}

Response:

{"status": "ok"}

#List Custom Fields Assigned to a Company

Request:

{
  "service" : "company.custom_fields",
  "id" : 78
}

Response:

{
  "status":"ok",
  "customFields":[
    {
      "id" : 7206,
      "name" : "Industry",
      "value" : "Transportation" 
    },
    {
      "id" : 4149,
      "name" : "location"
    }, ...
  ]
}

#Person

#Create a Person

Request:

{
  "service": "person.create",
  "person": {
    "name": "Rosa Parks",
    "company": {"id": 233},
    "email": "rosa.parks@example.com",      // optional: a user with this email as username will be created
    "invite": true,                         // optional: when email is present, invite the user (email)
    "userGroup": "employee",                // optional: define the user group.  Permitted values :
                                            // "admin",
                                            // "contractor",
                                            // "employee"(default),
                                            // "pm"(Project Manager),
                                            // "leader"(Team Leader)

    "leaders": [
      {                                     // optional: the person will be linked to one or more team leaders
        "id": 32,                           //
        "name": "Jane Clark",               // you can use either the id(or xid), name, email or all fields
        "email": "jane.clark@example.com"   // in order to retrieve the team leader
      },                                    // if all mentioned : id>xid>email>name
      ...
    ]                                      
  }
}

Response:

{
  "status": "ok",
  "id": 455
}

#Get a Person

Request:

{
  "service": "person.get",
  "id": 455
}

Response:

{
  "status" : "ok",
  "person" : {
    "id" : 455,
    "name" : "Rosa Parks",
    "company" : {"id" : 233},
    "active" : true,
    "email": "rosa.parks@example.com",
    "userGroup": "employee",
    "leaders" : {"count" : 1}
  }
}

#Update a Person

Request:

{
  "service": "person.update",
  "person": {
    "id": 455,
    "name": "Rosa Parks",
    "email": "rosa.parks@example.com",      //optional: the person email and username will be updated
    "invite": true,                         //optional: when email is present, invite the user (email)
    "userGroup": "employee",                //optional: update the user group.  Permitted values :
                                            // "admin",
                                            // "contractor",
                                            // "employee"(default),
                                            // "pm"(Project Manager),
                                            // "leader"(Team Leader)

    "leaders": [
      {                                     //optional: the person will be linked to one or more team leaders
        "id": 32,                           //
        "name": "Jane Clark",               // you can use either the id(or xid), name, email or all fields
        "email": "jane.clark@example.com"   // in order to retrieve the team leader
      },                                    // if all mentioned : id>xid>email>name
      ...
    ]                                      

  }
}

Response:

{"status" : "ok"}

#List Persons

Request:

{
  "service": "person.list",
  "company" : {"id" : 233}
}

Response:

{
  "status": "ok",
  "people": [
    {
      "id": 455,
      "name" : "Rosa Parks",
      "company": {"id" : 233},
      "active" : true,
      "email": "rosa.parks@example.com",
      "userGroup": "employee",
      "leaders" : {"count" : 1}
    }, ...
  ]
}

#List Team Leaders of a Person

Request:

{
  "service": "person.leaders",
  "id" : 455
}

Response:

{
  "status": "ok",
  "leaders": [
    {
      "id": 32,
      "name" : "Jane Clark",
      "company": {"id" : 233},
      "active" : true,
      "email": "jane.clarks@example.com",
      "userGroup": "leader",
      "leaders" : {"count" : 1}
    }, ...
  ]
}

#Activate a Person

Request:

{
  "service": "person.activate",
  "id": 455
}

Response:

{"status": "ok"}

#Deactivate a Person

Request:

{
  "service": "person.deactivate",
  "id": 455
}

Response:

{"status": "ok"}

#Assign a Group to a Person

Request:

{
  "service" : "person.add_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#Unassign a Group to a Person

Request:

{
  "service" : "person.remove_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#List Groups Assigned to a Person

Request:

{
  "service" : "person.groups",
  "id" : 78
}

Response:

{
  "status":"ok",
  "groups":[
    {
      "id":4787,
      "name":"US",
      "groups":{"count":4}
    }, ...
  ]
}

#Set a Custom Field Value to a Person

Request:

{
  "service" : "person.set_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 4879,
    "value" : "Salt Lake City, UT, USA"
  }
}

Response:

{"status": "ok"}

#Clear a Person Custom Field Value

Request:

{
  "service" : "person.clear_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 4879
  }
}

Response:

{"status": "ok"}

#List Custom Fields Assigned to a Person

Request:

{
  "service" : "person.custom_fields",
  "id" : 78
}

Response:

{
  "status":"ok",
  "customFields":[
    {
      "id" : 4879,
      "name" : "location",
      "value" : "Salt Lake City, UT, USA"
    }, ...
  ]
}

#Project

#Create a Project

Request:

{
  "service": "project.create",
  "project": {
    "name": "Development",
    "startDate": "2017-10-13", //optional, default 1st current month
    "description" : "some description ...", //optional
    "company": {"id": 233}
  }
}

Response:

{
  "status": "ok",
  "id": 321
}

#Get a Project

Request:

{
  "service": "project.get",
  "id": 321
}

Response:

{
  "status" : "ok",
  "project" : {
    "id" : 321,
    "name" : "Development",
    "startDate": "2017-10-13",
    "description" : "some description ...",
    "company" : {"id" : 233},
    "subprojects" : {"count" : 2},
    "active" : true
  }
}

#Update a Project

Request:

{
  "service" : "project.update",
  "project" : {
    "id" : 321,
    "name" : "newName",
    "startDate": "2017-10-13",
    "description" : "some description ..."
  }
}

Response:

{"status" : "ok"}

#List Projects

Request:

{
  "service": "project.list",
  "company" : {"id" : 233}
}

Response:

{
  "status": "ok",
  "projects": [
    {
      "id": 321,
      "name" : "Development",
      "startDate": "2017-10-13",
      "description" : "some description ...",
      "company": {"id" : 233},
      "subprojects" : {"count" : 2},
      "active" : true
    }, ...
  ]
}

#Activate a Project

Request:

{
  "service": "project.activate",
  "id": 321
}

Response:

{"status": "ok"}

#Deactivate a Project

Request:

{
  "service": "project.deactivate",
  "id": 321
}

Response:

{"status": "ok"}

#Assign a Specific Task to a Project

Request:

{
  "service" : "project.attach_specific_task",
  "id" : 78,
  "task" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#Unassign a Specific Task to a Project

Request:

{
  "service" : "project.detach_specific_task",
  "id" : 78,
  "task" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#List Specific Tasks Assigned to a Project

Request:

{
  "service" : "project.specific_tasks",
  "id" : 78
}

Response:

{
 "status" : "ok",
 "disabled" : false,  //default : false
 "specificTasks": [
   {
     "name" : "Administration",
     "id" : 345,
     "active":true
   }, ...
 ]
}

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

Request:

{
  "service" : "project.enable_specific_tasks",
  "id" : 78
}

Response:

{"status" : "ok"}

#Disable Specific Tasks for a Project

Request:

{
  "service" : "project.disable_specific_tasks",
  "id" : 78
}

Response:

{"status" : "ok"}

#Assign an Exclusive Member to a Project

Request:

{
  "service" : "project.attach_member",
  "id" : 78,
  "person" : {  // "person" or "group"
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#Unassign an Exclusive Member to a Project

Request:

{
  "service" : "project.detach_member",
  "id" : 78,
  "person" : {  // "person" or "group"
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#List Exclusive Members Assigned to a Project

Request:

{
  "service" : "project.members",
  "id" : 78
}

Response:

{
 "status" : "ok",
 "members": [
   {
     "name" : "John Le Carré",
     "id" : 345
   }, ...
 ],
 "groups": [
   {
     "name" : "US",
     "id" : 978
   }, ...
 ]
}

#Assign a Project Manager to a Project

Request:

{
  "service" : "project.attach_manager",
  "id" : 78,
  "person" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#Unassign a Project Manager to a Project

Request:

{
  "service" : "project.detach_manager",
  "id" : 78,
  "person" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#List Project Managers Assigned to a Project

Request:

{
  "service" : "project.managers",
  "id" : 78
}

Response:

{
 "status" : "ok",
 "members": [
   {
     "name" : "John Le Carré",
     "id" : 345,
     "email": "jlcarr@example.com",
     "active": true
   }, ...
 ]
}

#Assign a Group to a Project

Request:

{
  "service" : "project.add_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#Unassign a Group to a Project

Request:

{
  "service" : "project.remove_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#List Groups Assigned to a Project

Request:

{
  "service" : "project.groups",
  "id" : 78
}

Response:

{
  "status":"ok",
  "groups":[
    {
      "id":4787,
      "name":"US",
      "groups":{"count":4}
    }, ...
  ]
}

#Set a Custom Field Value to a Project

Request:

{
  "service" : "project.set_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 4879,
    "value" : "Salt Lake City, UT, USA"
  }
}

Response:

{"status": "ok"}

#Clear a Project Custom Field Value

Request:

{
  "service" : "project.clear_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 4879
  }
}

Response:

{"status": "ok"}

#List Custom Fields Assigned to a Project

Request:

{
  "service" : "project.custom_fields",
  "id" : 78
}

Response:

{
  "status":"ok",
  "customFields":[
    {
      "id" : 4879,
      "name" : "location",
      "value" : "Salt Lake City, UT, USA"
    }, ...
  ]
}

#Subproject

#Create a Subproject

Request:

{
  "service": "subproject.create",
  "subproject": {
    "name": "Prototype",
    "project": {"id": 321}
  }
}

Response:

{
  "status": "ok",
  "id": 765
}

#Get a Subproject

Request:

{
  "service": "subproject.get",
  "id": 765
}

Response:

{
  "status" : "ok",
  "subproject" : {
    "id" : 765,
    "name" : "Prototype",
    "project" : {"id" : 765},
    "active" : true
  }
}

#Update a Subproject

Request:

{
  "service" : "subproject.update",
  "subproject" : {
    "id" : 765,
    "name" : "newName"
  }
}

Response:

{"status" : "ok"}

#List Subprojects

Request:

{
  "service": "subproject.list",
  "project" : {"id" : 765}
}

Response:

{
  "status": "ok",
  "subprojects": [
    {
      "id" : 765,
      "name" : "Prototype",
      "project" : {"id" : 765},
      "active" : true
    }, ...
  ]
}

#Activate a Subproject

Request:

{
  "service": "subproject.activate",
  "id": 765
}

Response:

{"status": "ok"}

#Deactivate a Subproject

Request:

{
  "service": "subproject.deactivate",
  "id": 765
}

Response:

{"status": "ok"}

#Assign a Specific Task to a Subproject

Request:

{
  "service" : "subproject.attach_specific_task",
  "id" : 86,
  "task" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#Unassign a Specific Task to a Subproject

Request:

{
  "service" : "subproject.detach_specific_task",
  "id" : 86,
  "task" : {
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#List Specific Tasks Assigned to a Subproject

Request:

{
  "service" : "subproject.specific_tasks",
  "id" : 86
}

Response:

{
 "status" : "ok",
 "disabled" : false,  //default : false
 "specificTasks": [
   {
     "name" : "Administration",
     "id" : 345,
     "active":true
   }, ...
 ]
}

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

Request:

{
  "service" : "subproject.enable_specific_tasks",
  "id" : 78
}

Response:

{"status" : "ok"}

#Disable Specific Tasks for a Subproject

Request:

{
  "service" : "subproject.disable_specific_tasks",
  "id" : 78
}

Response:

{"status" : "ok"}

#Assign an Exclusive Member to a Subproject

Request:

{
  "service" : "subproject.attach_member",
  "id" : 765,
  "person" : {  // "person" or "group"
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#Unassign an Exclusive Member to a Subproject

Request:

{
  "service" : "subproject.detach_member",
  "id" : 765,
  "person" : {  // "person" or "group"
    "id" : 43
  }
}

Response:

{"status" : "ok"}

#List Exclusive Members Assigned to a Subproject

Request:

{
  "service" : "subproject.members",
  "id" : 765
}

Response:

{
 "status" : "ok",
 "members": [
   {
     "name" : "Peter Flemming",
     "id" : 350
   }, ...
 ],
 "groups": [
   {
     "name" : "US",
     "id" : 978
   }, ...
 ]
}

#Assign a Group to a Subproject

Request:

{
  "service" : "subproject.add_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#Unassign a Group to a Subproject

Request:

{
  "service" : "subproject.remove_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#List Groups Assigned to a Subproject

Request:

{
  "service" : "subproject.groups",
  "id" : 78
}

Response:

{
  "status":"ok",
  "groups":[
    {
      "id":4787,
      "name":"US",
      "groups":{"count":4}
    }, ...
  ]
}

#Set a Custom Field Value to a Subproject

Request:

{
  "service" : "subproject.set_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 4879,
    "value" : "Salt Lake City, UT, USA"
  }
}

Response:

{"status": "ok"}

#Clear a Subproject Custom Field Value

Request:

{
  "service" : "subproject.clear_custom_field_value",
  "id" : 78,
  "customField" : {
    "id" : 4879
  }
}

Response:

{"status": "ok"}

#List Custom Fields Assigned to a Subproject

Request:

{
  "service" : "subproject.custom_fields",
  "id" : 78
}

Response:

{
  "status":"ok",
  "customFields":[
    {
      "id" : 4879,
      "name" : "location",
      "value" : "Salt Lake City, UT, USA"
    }, ...
  ]
}

#Task

#Create a Task

Request:

{
  "service": "task.create",
  "task": {
    "name": "Meeting",
    "company": {"id": 233}
  }
}

Response:

{
  "status": "ok",
  "id": 955
}

#Get a Task

Request:

{
  "service": "task.get",
  "id": 955
}

Response:

{
  "status" : "ok",
  "task" : {
    "id" : 955,
    "name" : "Meeting",
    "company" : {"id" : 233},
    "active" : true
  }
}

#Update a Task

Request:

{
  "service" : "task.update",
  "task" : {
    "id" : 955,
    "name" : "newName"
  }
}

Response:

{"status" : "ok"}

#List Tasks

Request:

{
  "service": "task.list",
  "company" : {"id" : 233}
}

Response:

{
  "status": "ok",
  "tasks": [
    {
      "id" : 955,
      "name" : "Meeting",
      "company" : {"id" : 233},
      "active" : true
    }, ...
  ]
}

#Activate a Task

Request:

{
  "service": "task.activate",
  "id": 955
}

Response:

{"status": "ok"}

#Deactivate a Task

Request:

{
  "service": "task.deactivate",
  "id": 955
}

Response:

{"status": "ok"}

#Assign a Group to a Task

Request:

{
  "service" : "task.add_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#Unassign a Group to a Task

Request:

{
  "service" : "task.remove_group",
  "id" : 78,
  "group" : {
    "id" : 105
  }
}

Response:

{"status": "ok"}

#List Groups Assigned to a Task

Request:

{
  "service" : "task.groups",
  "id" : 78
}

Response:

{
  "status":"ok",
  "groups":[
    {
      "id":4787,
      "name":"US",
      "groups":{"count":4}
    }, ...
  ]
}

#Group

#Create a Group

Request:

{
  "service": "group.create",
  "group": {
    "name": "Texas",
    "parent": {"id": 4787} //optional: if not present, the group will be created at the root level
  }
}

Response:

{
  "status": "ok",
  "id": 1005
}

#Get a Group

Request:

{
  "service": "group.get",
  "id": 1005
}

Response:

{
  "status" : "ok",
  "group" : {
    "id" : 1005,
    "name" : "Texas",
    "parent" : {"id" : 4787}
  }
}

#Update a Group

Request:

{
  "service" : "group.update",
  "group" : {
    "id" : 1005,
    "name" : "Texas - Austin"
  }
}

Response:

{"status" : "ok"}

#Delete a Group

Request:

{
  "service" : "group.delete",
  "id" : 1005,
  "force" : true //optional:  default is false. Force deletion even when the group has been assigned to entities
  }
}

Response:

{"status" : "ok"}

#List Groups Assigned to an Entity

Request:

{
  "service": "group.list",
  "company" : {"id" : 233} // "absence", "company", "project", "subproject", "task" or "person"
}

Response:

{
  "status": "ok",
  "groups":[
    {
      "id":4787,
      "name":"US",
      "groups":{"count":4}
    }, ...
  ]
}

#List Entities Assigned to a Group

Request:

{
  "service": "group.assignments",
  "id" : 4787 // group id
}

Response:

{
  "status": "ok",
  "companies": [
    {
      "id" : 233,
      "name" : "myCompany",
      "active" : true
    }, ...
  ],
  "people": [
    {
      "id": 455,
      "name" : "Rosa Parks",
      "active" : true,
      "email": "rosa.parks@example.com"
    }, ...
  ],
  ...     //"companies", "projects", "subprojects", "tasks", "people", "absences"
}

#Groups Tree

Request:

{
  "service": "group.tree"
}

Response:

{
  "groups": [
    {
      "id":4521,
      "name":"Country",
      "groups":[
        {
          "id":4787,
          "name":"US"
        }
      ]
    }
  ]
}

#Custom Field

#List Custom Fields

Request:

{
  "service": "custom_field.list"
}

Response:

{
  "customFields": [
    {
      "id":4641,
      "name":"Company address",
      "availableFor":"Company - Customer"
    }
  ]
}

#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:

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

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:

{
  "service": "time_entry.get_entities",
  "company": {
    "id": 3
  },
  "date": "2017-06-16"
}

Response:

{
  "projects":[
    {
      "id":30,
      "name":"Dev",
      "active":true,
      "subprojects":{"count":2}
    },
    {
      "id":4131,
      "name":"Marketing",
      "active":true,
      "subprojects":{"count":0}
    },
    {
      "id":4128,
      "name":"Sales",
      "active":true,
      "subprojects":{"count":0}
    }
  ]
}

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:

{
  "service": "time_entry.get_entities",
  "project": {
    "id": 30
  },
  "date": "2017-06-16"
}

Response:

{
  "subprojects":[
    {
      "active":true,
      "name":"Analyse",
      "id":37
    },
    {
      "active":true,
      "name":"Proto",
      "id":31
    }
  ]
}

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:

{
  "service": "time_entry.get_tasks",
  "subproject": {
    "id": 37
  },
  "date": "2017-07-16"
}

Response:

{
  "tasks":[
    {
      "active":true,
      "name":"Administration",
      "id":17
    },
    {
      "active":true,
      "name":"Meetings",
      "id":18
    },
    {
      "active":true,
      "name":"Research",
      "id":19
    }
  ]
}

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

#Create a Time Entry

Request:

{
  "service": "time_entry.create",
  "subproject": {
    "id": 37
  },  //company.id, project.id, subproject.id or absence.id
  "task":{
    "id": 17
  },  //mandatory if any
  "date": "2017-08-05",
  "hours": 8,
  "comment": "some comment"
}

Response:

{
  "status":"ok",
  "timeEntry":{
    "hours":8.0,
    "status":"d",
    "subproject":{
      "id":37,
      "name":"Analyse",
      "active":true
    },
    "task":{
      "name":"Administration",
      "id":17,
      "active":true
    },
    "id":500901,
    "date":"2017-09-29",
    "comment":"some comment"
  }
}

#Update a Time Entry

Request:

{
  "service": "time_entry.update",
  "id":500901,
  "subproject":{
    "id": 37
  },//company.id, project.id, subproject.id or absence.id
  "task":{
    "id": 17
  },//mandatory if there are tasks defined, and not an absence
  "date": "2017-09-29",
  "hours": 7,
  "comment": "updated comment"
}

Response:

{
  "status":"ok",
  "timeEntry":{
    "hours":7.0,
    "status":"d",
    "subproject":{
      "id":37,
      "name":"Analyse",
      "active":true
    },
    "task":{
      "name":"Administration",
      "id":17,
      "active":true
    },
    "id":500901,
    "date":"2017-09-29",
    "comment":"updated comment"
  }
}

#Get a Time Entry

Request:

{
  "service": "time_entry.get",
  "id": 500901,
  "date":"2017-09-29"
}

Response:

{
 "status":"ok",
 "timeEntry":{
     "hours":7.0,
     "status":"d",
     "subproject":{
       "id":37,
       "name":"Analyse",
       "active":true
     },
     "task":{
       "name":"Administration",
       "id":17,
       "active":true
     },
     "id":500901,
     "date":"2017-09-29",
     "comment":"updated comment"
   }
}

#Delete a Time Entry

Request:

{
  "service": "time_entry.delete",
  "id": 500901,
  "date":"2017-09-29"
}

Response:

{"status" : "ok"}

#List Time Entries

Request:

{
 "service": "time_entry.list",
 "person" : {
   "id": 2
 },
 "from": "2017-09-01",
 "to": "2017-09-30"
}

Response:

{
 "status":"ok",
 "timeEntries":[
   {
     "hours":7.0,
     "status":"d",
     "subproject":{
       "id":37,
       "name":"Analyse",
       "active":true
     },
     "task":{
       "name":"Administration",
       "id":17,
       "active":true
     },
     "id":500901,
     "date":"2017-09-29",
     "comment":"updated comment"
   },
   ...
 ]
}

#Submit Time Entry

Request:

{
 "service": "time_entry.submit",
 "person" : {
   "id": 2
 },
 "from": "2017-10-01", // As an alternative you can use "id": 500001,"date":"2017-11-07"
 "to": "2017-10-15"    // instead of "from", "to", "id" being the time entry id
}

Response:

{"status":"ok"}

#Approve Time Entry

Request:

{
 "service": "time_entry.approve",
 "person" : {
   "id": 2
 },
 "from": "2017-10-01", // As an alternative you can use "id": 500001,"date":"2017-11-07"
 "to": "2017-10-15"    // instead of "from", "to", "id" being the time entry id
}

Response:

{"status":"ok"}

#Reject Time Entry

Request:

{
 "service": "time_entry.reject",
 "person" : {
   "id": 2
 },
 "from": "2017-10-01", // As an alternative you can use "id": 500001,"date":"2017-11-07"
 "to": "2017-10-15",    // instead of "from", "to", "id" being the time entry id
 "memo": "Rejection reason"   // The rejection reason sent to the employee via email
}

Response:

{"status":"ok"}

#Lock Time Entry

Request:

{
 "service": "time_entry.lock",
 "person" : {
   "id": 2
 },
 "from": "2017-10-01", // As an alternative you can use "id": 500001,"date":"2017-11-07"
 "to": "2017-10-15"    // instead of "from", "to", "id" being the time entry id
}

Response:

{"status":"ok"}

#Unlock Time Entry

Request:

{
 "service": "time_entry.unlock",
 "person" : {
   "id": 2
 },
 "from": "2017-10-01", // As an alternative you can use "id": 500001,"date":"2017-11-07"
 "to": "2017-10-15"    // instead of "from", "to", "id" being the time entry id
}

Response:

{"status":"ok"}

#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:

call the service time_entry.export to initiate a new export job and receive a new job ID.
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.

API Keys

“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:

{
  "service": "time_entry.export",
  "from": "2017-10-01",
  "to" : "2017-10-30",
  "show" : "all", // Optional default "all"
  "keys" : ["company", "companyId", "hours"],
  "statusFilters" : ["l", "a"], // optional
  "company":{ "id":8695 },  // optional to filter the data for a specific and single entity
                            // accept "company", "project", "subproject", "person", "task", "absence"
  "gids" : [4588,8977], //optional
  "outputFormat" : "array" // optional to get results as array of arrays (If not defined, the output will be CSV)
}

Response:

{
  "status":"ok",
  "job": {
    "status":"running",
    "id":1148
  }
}

#Get Job Info

Request:

{
  "service":"time_entry.get_job_info",
  "id":1148,
  "outputFormat" : "array" // optional to get results as array of arrays (If not defined, the output will be CSV)
}

Response:

{
  "status":"ok",
  "job": {
    "status":"running",
    "id":1148
  }
}

OR if it’s done

Response:

{
  "status":"ok",
  "job": {
    "status":"done",
    "id":1148,
    "result":"Entreprise,Heures\nBranch,\"7,000\"\nMyCompany,\"63,000\"\n ..."
  }
}

Case Study: A Custom API Integration by Taptu

The Beebole customer and IT advisory Taptu shares their insights on custom integrations.