API

Revision 8.122.0 (February 24, 2026)

Introduction to OroTimesheet API

The OroTimesheet API (Application Programming Interface) is an interface that allow you to exchange data between OroTimesheet and other software. This API allows you to read and write data in most of options of OroTimesheet such as Projects, Employees, Timesheets, etc. This API is based on industry standard components HTTPS (Secure Hypertext Transfer Protocol) and XML (Extensible Markup Language).

OpenAPI Specifications

Machine-readable specification files for automated code generation, API testing, and AI assistant integration:

Target Audience

This document is intended for developers of applications that will connect to the OroTimesheet.com web site.

Internationalization and Character Sets

OroTimesheet uses UTF-8 encoding to store and display characters in the application.

Prerequisites

The API works only with OroTimesheet.com. To activate the API, from OroTimesheet, select the tab Plus then select the menu Configuration | Application configuration. Check the box Allow access to data via API from the section named API (Application Programming Interface). Note that the API can be fully used even if you are in trial mode.

API password

Each OroTimesheet account has a unique API password which can be found in the menu Configuration | Application configuration (section API (Application Programming Interface)) via the tab Plus. A new API password can be generated just by clicking the button Change API password. Note that if you generate a new API password for your account, the previous password will not work anymore to perform API requests.

This API password is used for two things:

To prevent unauthorized access to your OroTimesheet data.
To know which OroTimesheet account data you want to access. Indeed, each OroTimesheet password is unique. Two different accounts will never have the same password.

API requests

All API requests must be made via SSL over HTTPS. Requests must be submitted via HTTPS POST in the following format:

<request app="orotimesheet" version="8" password="abcdef-123456">
  <!-- Request_details -->
</request>

Replace abcdef-123456 by your API password then replace Request_details by valid request instructions. See section API request types below for more information about valid requests instructions.

Here is an example API request that will add a new sub-project in a project record:

<request app="orotimesheet" version="8" password="abcdef-123456">
 <sub_project_add>
  <project_id>5271</project_id>
  <description>Phase 3</description>
  <position>3</position>
  <time_bank>accumulated_time</time_bank>
 </sub_project_add>
</request>

If the example API request above is successful, the API will return an XML as the following:

<response app="orotimesheet" version="8" status="1">
 <sub_project_id>3834</sub_project_id>
</response>

On the other side, if the example API request above fails, the API will return an XML as the following:

<response app="orotimesheet" version="8" status="0">
 <error code="1102">
  <![CDATA[Record duplicate error. A record with the supplied value already exists. There is already a sub-project with this description for this project.]]>
 </error>
</response>

In short, you have to verify the status attribute of the response tag to know if the API request was successful or not. A value of 1 means successful while a value of 0 means that an error occurred. Additional information will be also included in the XML result according to the kind of result and/or the kind of request you made. Refer to the section API request types below for more information about results each request type can produce.

Note about strings

Note that all strings contained in responses are enclosed in a CDATA section. When you send a request, you can as well enclose strings in CDATA sections for example when these strings contain special characters. However, if your strings does not include special characters, it is not mandatory to use CDATA section in your XML requests.

Note about date formats

Date are always returned in the following format: YYYY-MM-DD

Ex.: 2025-04-25

DateTime are always returned in the following format YYYY-MM-DD HH:MM:SS

Ex.: 2025-04-25 23:15:00

Time are always returned in the following format: HH:MM:SS

When you have to pass Date, Time or DateTime to an API request, you must also respect these formats as well else your request could be rejected or return an error message.

Note about number format

Decimal numbers are always returned with a dot as the decimal separator and nothing as the thousands separator. Ex.: 23941.60

When you have to pass decimal numbers to an API request, numbers must be passed in this format as well else your request could be rejected or return an error message.

Note about user defined fields

If you defined user defined fields, when applicable, these fields will be returned in the response as well. In such case, the tag for these fields will be named udfXXXX where XXXX is the user defined field number generated by the system at user defined field creation time. An attribute named description will be added to the tag as well to let you know the description of the user defined field.

You can insert and update data in user defined fields as well. In such case, just use the tag name that correspond to the user defined field to update. You do not have to specify the description attribute when adding or updating data in user defined fields. See examples in sections customer_get and customer_add below for more information about user defined fields.

API URL (End point)

Always use the following URL to send your XML requests: https://app.orotimesheet.com/api.php

This url requires only one parameter (POST only) named xml_request.

How to send a request and get the response

You can use any programming language you want to send the request to the API.

PHP example

Here is a PHP example that is using CURL to send a request and retrieve the response. This example generates an HTML page and prints the result in a textarea object:

<?php
 $xml = '<request app="orotimesheet" version="8" password="abcdef-123456">
          <sub_project_add>
           <project_id>5271</project_id>
           <description>Phase 3</description>
           <position>3</position>
           <time_bank>accumulated_time</time_bank>
          </sub_project_add>
         </request>';
 $postfields = array('xml_request'=>$xml);
 $ch = curl_init();
 curl_setopt($ch, CURLOPT_URL, 'https://app.orotimesheet.com/api.php');
 curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
 curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
 curl_setopt($ch, CURLOPT_POST, 1);
 curl_setopt($ch, CURLOPT_POSTFIELDS, $postfields);
 curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
 $result = curl_exec($ch);
?>

<!DOCTYPE html>
<html>
 <head>
  <title>test</title>
 </head>
 <body>
  <textarea rows="200" cols="200"><?php echo $result; ?></textarea>
 </body>
</html>

Visual Basic example

Here is a Visual Basic example that retrieves the customer list. The variable API_PW should be set to your API password. This example prints the result in the debugger window:

Sub TestHTTPPost()
   Set objHTTP = CreateObject("MSXML2.ServerXMLHTTP")
   URL = "https://app.orotimesheet.com/api.php"
   objHTTP.Open "POST", URL, False
   objHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
   objHTTP.send ("xml_request=<request app=""orotimesheet"" version=""5"" password=""" & API_PW & """><customer_list></customer_list></request>")
   Debug.Print objHTTP.responseText
End Sub

List of API request types

employee_list

Get entire list of employees in a summary format

Once the list of employees retrieved, you can use the employee_get request type to retrieve the complete record of a specific employee using the employee_id retrieved.

XML request example:

<request app="orotimesheet" version="8" password="abcdef-123456">
 <employee_list>
 </employee_list>
</request>

Response successful example:

<response app="orotimesheet" version="8" status="1">
 <employee>
  <employee_id>1</employee_id>
  <name><![CDATA[John Doe]]></name>
  <email><![CDATA[jdoe@orotimesheet.com]]></email>
  <status>active</status>
 </employee>
 <employee>
  <employee_id>14</employee_id>
  <name><![CDATA[Janet White]]></name>
  <email><![CDATA[janet@orotimesheet.com]]></email>
  <status>active</status>
 </employee>
</response>

employee_get

Get an employee record

XML request example:

<request app="orotimesheet" version="8" password="abcdef-123456">
 <employee_get>
  <employee_id>14</employee_id>
 </employee_get>
</request>

employee_id: integer - Required - Id of the employee to retrieve. If the employe id specified does not exist, the request will fail.

Response successful example:

<response app="orotimesheet" version="8" status="1">
 <employee>
  <empployee_id>14</empployee_id>
  <name><![CDATA[Janet White]]></name>
  <email><![CDATA[janet@orotimesheet.com]]></email>
  <status>active</status>
  <type>0</type>
  <employee_group_description><![CDATA[Everybody]]></employee_group_description>
  <employee_group_id>0</employee_group_id>
  <category_description><![CDATA[Default category]]></category_description>
  <category_id>0</category_id>
  <notes><![CDATA[This is a good employee]]></notes>
  <sin><![CDATA[125-147-874]]></sin>
  <hire_date>2005-08-25</hire_date>
  <max_minutes_enterable>480</max_minutes_enterable>
  <max_minutes_enterable_type>1</max_minutes_enterable_type>
  <max_minutes_enterable_use_group_settings>no</max_minutes_enterable_use_group_settings>
  <minutes_usually_worked_per_week>2400</minutes_usually_worked_per_week>
  <minutes_usually_worked_per_week_use_group_settings>yes</minutes_usually_worked_per_week_use_group_settings>
  <billing_rate>50.0000</billing_rate>
  <billing_rate_type>1</billing_rate_type>
  <billing_rate_billable>yes</billing_rate_billable>
  <billing_use_group_settings>no</billing_use_group_settings>
  <cost_rate>26.7500</cost_rate>
  <cost_affect_cost>yes</cost_affect_cost>
  <cost_use_group_settings>no</cost_use_group_settings>
  <time_bank_allow_negative>no</time_bank_allow_negative>
  <time_bank_allow_negative_use_group_settings>yes</time_bank_allow_negative_use_group_settings>
  <time_bank_overtime_calc_use_group_settings>yes</time_bank_overtime_calc_use_group_settings>
  <time_bank_overtime_calc_type>2</time_bank_overtime_calc_type>
  <time_bank_overtime_calc_after_nbr_minutes>2400</time_bank_overtime_calc_after_nbr_minutes>
  <time_bank_overtime_calc_multiplier_factor>1.5000</time_bank_overtime_calc_multiplier_factor>
  <time_bank_balance_accumulated>600</time_bank_balance_accumulated>
  <time_bank_balance_vacations>4800</time_bank_balance_vacations>
  <time_bank_balance_sick>480</time_bank_balance_sick>
  <udf327 description="Position"><![CDATA[Marketing]]></udf327>
  <udf348 description="Part time">no</udf348>
  <employee_group>
   <employee_group_id>0</employee_group_id>
  </employee_group>
  <employee_group>
   <employee_group_id>5</employee_group_id>
  </employee_group>
 </employee>
</response>

See request type employee_edit for information about fields. Note that employee_group_description and employee_group_id contain information about the base group of the employee while sections employee_group contain the list of each group id of which the employee is a member.

employee_add

Add a new employee

XML request example:

<request app="orotimesheet" version="8" password="abcdef-123456">
 <employee_add>
  <name><![CDATA[Janet White]]></name>
  <email><![CDATA[<Janet.White@orotimesheet.com>]]></email>
  <employee_group_description><![CDATA[Group of Mechanical Engineers]]></employee_group_description>
  <category_id>3</category_id>
  <billing_rate>150.00</billing_rate>
  <billing_rate_billable>yes</billing_rate_billable>
  <billing_rate_type>1</billing_rate_type>
  <billing_use_group_settings>no</billing_use_group_settings>
  <hire_date>2023-02-23</hire_date>
 </employee_add>
</request>

name: string(50) - Required - Employee name. If the employee name already exists, the request will fail.

email: string (60) - Required - Employee email. If the employee email is already used by another user (even in another account), the request will fail. The e-mail address must be in a valid e-mail format.

notes: text

status: If specified, you must specify active or inactive. Default is active.

employee_group_id: integer - Id of the employee base group. If not specified, the default group Everybody will be used.

employee_group_description: string (35) - It allows you to specify the employee base group using the group description instead of its id. The API will retrieve the employee_group_id for you. If employee_group_id is also specified, this field will be ignored.

category_id: integer - Id of the employee category. If not specified, the default category will be used.

category_description: string (35) - It allows you to specify the category using the category description instead of its id. The API will retrieve the category_id for you. If category_id is also specified, this field will be ignored.

sin: string (30)

hire_date: date

max_minutes_enterable: integer - Maximum minutes enterable per day or per week. See max_minutes_enterable_type below.

max_minutes_enterable_type: integer - 1=per day, 2=per week.

max_minutes_enterable_use_group_settings: string - You must specify yes or no.

minutes_usually_worked_per_week: integer - Number of minutes usually worked week.

minutes_usually_worked_per_week_use_group_settings: string - You must specify yes or no.

billing_rate: decimal

billing_rate_billable: string - You must specify yes or no.

billing_rate_type: integer - 0=Billing rate based on activity type rate, 1=Billing rate based on employee rate,

billing_use_group_settings: string - You must specify yes or no.

cost_rate: decimal

cost_affect_cost: string - You must specify yes or no.

cost_use_group_settings: string - You must specify yes or no.

time_bank_allow_negative: string - You must specify yes or no.

time_bank_allow_negative_use_group_settings: string - You must specify yes or no.

time_bank_overtime_calc_type: integer - 0=No overtime, 1=Overtime calculated per day, 2=Overtime calculated per week.

time_bank_overtime_calc_after_nbr_minutes: integer - Overtime will start to be calculated after the number of minutes indicated here.

time_bank_overtime_calc_multiplier_factor: decimal - Overtime will be multiplied by this value.

time_bank_overtime_calc_use_group_settings: string - You must specify yes or no.

For security reason, other fields of the employee records such as access or supervision rights cannot be edited via the API. You can only edit it via the application.

Response successful example:

<response app="orotimesheet" version="8" status="1">
 <employee_id>14</employee_id>
</response>

employee_id: Id of the new created employee.

employee_edit

Edit an existing employee

XML request example:

<request app="orotimesheet" version="8" password="abcdef-123456">
 <employee_edit>
  <employee_id>14</employee_id>
  <notes><![CDATA[This employee is still a very good employee]]></notes>
  <email><![CDATA[<Janet.White@orotimesheet.com>]]></email>
  <category_id>3</category_id>
  <billing_rate>54.25</billing_rate>
  <billing_rate_billable>yes</billing_rate_billable>
  <billing_rate_type>1</billing_rate_type>
  <billing_use_group_settings>no</billing_use_group_settings>
  <hire_date>2006-09-14</hire_date>
  <max_minutes_enterable>450</max_minutes_enterable>
  <max_minutes_enterable_type>1</max_minutes_enterable_type>
 </employee_edit>
</request>

employee_id: integer - Required - Id of the employee to edit. If the employee id specified does not exist, the request will fail.

name: string(50) - Employee name. If the employee name already exists, the request will fail.

email: string (60) - If you provide an e-mail address, the e-mail address must be in a valid e-mail format.

notes: text

status: If specified, you must specify active or inactive.

employee_group_id: integer - Id of the employee base group.

category_id: integer - Id of the employee category.