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

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: 2048KB/day

• and number of requests: 4000 requests/day

If you reach this limit feel free to contact us.

Request

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

https://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.

  {
  "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 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

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

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

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

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

“statusFilters” : this represents the time record filter.

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

“outputFormat” : “array” : this parameter is optional. It allows 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 ..."
  }
}