Difference between revisions of "API"

From TimeMD Help
Jump to: navigation, search
(→‎Account Related Properties)
 
(65 intermediate revisions by the same user not shown)
Line 13: Line 13:
 
To register a device, your first login with a company's primary account login. You must pass the action ‘regiser_device’, and you must include the company's username and password:
 
To register a device, your first login with a company's primary account login. You must pass the action ‘regiser_device’, and you must include the company's username and password:
  
−
''https://login.timemd.com/login/api.php?action=register_device&username=demoent&password=demoent''
+
In return you will get the accounts API Key. You must include the given key for all subsequent API calls related to that device (i.e. clock_out, clock_in, etc.) See "Authentication" section below for more information regarding the action, "register_device".
−
 
 
−
In return you will get the accounts API Key. You must include the given key for all subsequent API calls related to that device (i.e. clock_out, clock_in, etc.)
 
  
 
<pre>
 
<pre>
Line 33: Line 31:
 
</result>
 
</result>
 
</pre>
 
</pre>
 +
 +
When you receive a status of 'followup' from any API action, you'll also be given a message to display to the user. For example:
 +
 +
<pre>
 +
<result>
 +
  <status>followup</status>
 +
  <message>Where you injured on the job today?</message>
 +
</result>
 +
</pre>
 +
 +
==  Authentication ==
 +
=== Registering A Device ===
 +
This is required before any subsequent API actions can be placed. Upon successful authentication, you will receive the accounts API Key. This should be saved on the device.
 +
 +
<b>Action</b>
 +
* register_device
 +
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| username
 +
| Yes
 +
| The username of the account to be registered.
 +
|-
 +
!scope="row"| password
 +
| Yes
 +
| The password of the account to be registered.
 +
|}
 +
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail'. On 'fail' a ''message'' field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.
  
 
== Tracking Time ==
 
== Tracking Time ==
Line 61: Line 94:
 
|-
 
|-
 
!scope="row"| job_idx
 
!scope="row"| job_idx
−
|  
+
| Maybe
 
| The TimeMD assigned ID of the job the user is to be clocked in under. If this parameter is not passed, the system will assume the primary job is being used “If” job tracking is required.
 
| The TimeMD assigned ID of the job the user is to be clocked in under. If this parameter is not passed, the system will assume the primary job is being used “If” job tracking is required.
 
|-
 
|-
 
!scope="row"| task_idx
 
!scope="row"| task_idx
−
|  
+
| Maybe
 
| The TimeMD assigned ID of the taks the user is to be clocked in under.
 
| The TimeMD assigned ID of the taks the user is to be clocked in under.
 +
|-
 +
!scope="row"| photo_bin
 +
| Maybe
 +
| The binary data of the photograph taken during the clock_in action. This is required on devices with a camera.
 +
|-
 +
!scope="row"| gps_lat
 +
| Maybe
 +
| The latitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.
 +
|-
 +
!scope="row"| gps_lon
 +
| Maybe
 +
| The longitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.
 
|}
 
|}
  
 
<b>Output</b>
 
<b>Output</b>
−
* The ''status'' field will either be 'ok' or 'fail'. On failure a ''message'' field will explain why.
+
* The ''status'' field will either be 'ok' or 'fail'. On 'fail' a ''message'' field will explain why.
  
 
=== Clocking Out ===
 
=== Clocking Out ===
Line 92: Line 137:
 
| Yes
 
| Yes
 
| The TimeMD assigned ID of the time entry the user is clocking out from.
 
| The TimeMD assigned ID of the time entry the user is clocking out from.
 +
|-
 +
!scope="row"| dept_idx
 +
| Yes
 +
| The TimeMD assigned department ID. If different then the department ID saved to existing time entry, system will automatically clock user in under the new ID.
 +
|-
 +
!scope="row"| job_idx
 +
| Maybe
 +
| The TimeMD assigned job ID. If passed and if different then the job ID saved to time entry, system will automatically clock user in under the new ID.
 +
|-
 +
!scope="row"| task_idx
 +
| Maybe
 +
| The TimeMD assigned task ID. If passed and if different then the task ID saved to time entry, system will automatically clock user in under the new ID.
 +
|-
 +
!scope="row"| photo_bin
 +
| Maybe
 +
| The binary data of the photograph taken during the clock_out action. This is required on devices with a camera.
 +
|-
 +
!scope="row"| gps_lat
 +
| Maybe
 +
| The latitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.
 +
|-
 +
!scope="row"| gps_lon
 +
| Maybe
 +
| The longitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.
 +
|}
 +
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail'. On 'fail' a ''message'' field will explain why.
 +
 +
=== Starting A Break ===
 +
This call lets you start a break for a user.
 +
 +
<b>Action</b>
 +
* start_break
 +
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| api_key
 +
| Yes
 +
| See Register a Device section for details.
 +
|-
 +
!scope="row"| user_idx
 +
| Yes
 +
| The TimeMD assigned ID of the user you would like to start a break with.
 +
|-
 +
!scope="row"| time_idx
 +
| Yes
 +
| The TimeMD assigned ID of the time entry the user is starting their break from.
 
|}
 
|}
  
 
<b>Output</b>
 
<b>Output</b>
−
* The ''status'' field will either be 'ok' or 'fail'. On failure a ''message'' field will explain why.
+
* The ''status'' field will either be 'ok' or 'fail''. On 'fail' a ''message'' field will explain why.
 +
 
 +
=== Ending A Break ===
 +
This call lets you start a break for a user.
 +
 
 +
<b>Action</b>
 +
* end_break
 +
 
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| api_key
 +
| Yes
 +
| See Register a Device section for details.
 +
|-
 +
!scope="row"| user_idx
 +
| Yes
 +
| The TimeMD assigned ID of the user you would like to end a break with.
 +
|-
 +
!scope="row"| time_idx
 +
| Yes
 +
| The TimeMD assigned ID of the time entry the user is ending their break from.
 +
|-
 +
!scope="row"| time_break_idx
 +
| Yes
 +
| The TimeMD assigned ID of the break entry the user is ending from.
 +
|}
 +
 
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail''. On 'fail' a ''message'' field will explain why.
 +
 
 +
== Data Management ==
 +
=== Adding Users ===
 +
Used to add new employees to your account.
 +
 
 +
<b>Action</b>
 +
* custom_add_employee
 +
 
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| api_key
 +
| Yes
 +
| See Register a Device section for details
 +
|-
 +
!scope="row"| employee_id
 +
| Yes
 +
| The Employee ID of the employee being added
 +
|-
 +
!scope="row"| first_name
 +
| Yes
 +
| First name of the employee
 +
|-
 +
!scope="row"| last_name
 +
| Yes
 +
| Last name of the employee
 +
|-
 +
!scope="row"| cell_number
 +
| Yes
 +
| Cell number for the employee. Format (123)456-7890
 +
|-
 +
!scope="row"| employee_status
 +
| Yes
 +
| Employee status. 1 = Active. 0 = Inactive
 +
|}
 +
 
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail'. On 'fail' a ''message'' field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.
 +
 
 +
=== Updating Users ===
 +
Used to add update employees.
 +
 
 +
<b>Action</b>
 +
* custom_update_employee
 +
 
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| api_key
 +
| Yes
 +
| See Register a Device section for details
 +
|-
 +
!scope="row"| employee_id
 +
| Yes
 +
| The Employee ID of the employee being updated
 +
|-
 +
!scope="row"| first_name
 +
| No
 +
| First name of the employee
 +
|-
 +
!scope="row"| last_name
 +
| No
 +
| Last name of the employee
 +
|-
 +
!scope="row"| cell_number
 +
| No
 +
| Cell number for the employee. Format (123)456-7890
 +
|-
 +
!scope="row"| employee_status
 +
| No
 +
| Employee status. 1 = Active. 0 = Inactive
 +
|}
 +
 
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail'. On 'fail' a ''message'' field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.
 +
 
 +
=== Adding Locations ===
 +
Used to add new locations.
 +
 
 +
<b>Action</b>
 +
* custom_add_location
 +
 
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| api_key
 +
| Yes
 +
| See Register a Device section for details
 +
|-
 +
!scope="row"| location_id
 +
| Yes
 +
| The Location ID of the location being added
 +
|-
 +
!scope="row"| location_name
 +
| Yes
 +
| Name of the location
 +
|-
 +
!scope="row"| location_time_zone
 +
| No
 +
| Time zone of the location
 +
|-
 +
!scope="row"| location_address1
 +
| No
 +
| Address of the location
 +
|-
 +
!scope="row"| location_address2
 +
| No
 +
| Address of the location
 +
|-
 +
!scope="row"| location_city
 +
| No
 +
| City of the location
 +
|-
 +
!scope="row"| location_state
 +
| No
 +
| State of the location
 +
|-
 +
!scope="row"| location_zip
 +
| No
 +
| Zip of the location
 +
|-
 +
!scope="row"| location_geo_address
 +
| No
 +
| GPS full address of the location in the following format: street, city, state, zip, country
 +
|-
 +
!scope="row"| location_geo_lat
 +
| No
 +
| Latitude of the location in decimal form
 +
|-
 +
!scope="row"| location_geo_lon
 +
| No
 +
| Longitude of the location in decimal form
 +
|-
 +
!scope="row"| location_geo_radius
 +
| No
 +
| Geo fence radius of the location
 +
|-
 +
!scope="row"| location_geo_active
 +
| No
 +
| Status of the geo fence: 1 = Active, 0 = Inactive
 +
|}
 +
 
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail'. On 'fail' a ''message'' field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.
 +
 
 +
=== Updating Locations ===
 +
Used to update an existing locations.
 +
 
 +
<b>Action</b>
 +
* custom_update_location
 +
 
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| api_key
 +
| Yes
 +
| See Register a Device section for details
 +
|-
 +
!scope="row"| location_id
 +
| Yes
 +
| The Location ID of the location being updated
 +
|-
 +
!scope="row"| location_name
 +
| Yes
 +
| Name of the location
 +
|-
 +
!scope="row"| location_time_zone
 +
| No
 +
| Time zone of the location
 +
|-
 +
!scope="row"| location_address1
 +
| No
 +
| Address of the location
 +
|-
 +
!scope="row"| location_address2
 +
| No
 +
| Address of the location
 +
|-
 +
!scope="row"| location_city
 +
| No
 +
| City of the location
 +
|-
 +
!scope="row"| location_state
 +
| No
 +
| State of the location
 +
|-
 +
!scope="row"| location_zip
 +
| No
 +
| Zip of the location
 +
|-
 +
!scope="row"| location_geo_address
 +
| No
 +
| GPS full address of the location in the following format: street, city, state, zip, country
 +
|-
 +
!scope="row"| location_geo_lat
 +
| No
 +
| Latitude of the location in decimal form
 +
|-
 +
!scope="row"| location_geo_lon
 +
| No
 +
| Longitude of the location in decimal form
 +
|-
 +
!scope="row"| location_geo_radius
 +
| No
 +
| Geo fence radius of the location
 +
|-
 +
!scope="row"| location_geo_active
 +
| No
 +
| Status of the geo fence: 1 = Active, 0 = Inactive
 +
|}
 +
 
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail'. On 'fail' a ''message'' field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.
  
 
== Read-Only Information ==
 
== Read-Only Information ==
Line 114: Line 474:
 
| Yes
 
| Yes
 
| See Register a Device section for details.
 
| See Register a Device section for details.
 +
|-
 +
!scope="row"| user_idx
 +
| No
 +
| If provided, the method will return data specific to that user. If not provided, method will return data specific to the account the API Key belongs too.
 +
|-
 +
!scope="row"| device_id
 +
| No
 +
| If provided, the method will return data specific to that device. If not provided, method will return data specific to the account the API Key belongs too.
 
|-
 
|-
 
!scope="row"| property
 
!scope="row"| property
 
| Yes
 
| Yes
−
| The property or properties that you would like to retrieve. You may specify multiple properties at once, just provide them separated by a pipe character ( | ), without spaces.
+
| The property or properties that you would like to retrieve. You may specify multiple properties at once, just provide them separated by a pipe character, without spaces.
 
|}
 
|}
  
Line 134: Line 502:
 
** name (name of the department)
 
** name (name of the department)
 
** location (name of the department is assigned too)
 
** location (name of the department is assigned too)
 +
* primary_job (the name of the primary job assigned to the user. If used, the primary_job_data property is automatically returned. The following properties are returned by the primary_job_data property:
 +
** idx (TimeMD assigned ID)
 +
** jobIdx (parent job ID)
 +
** name (name of job)
 +
** jobId (User assigned job ID)
 
* user_perms (permissions assigned to the user, 1 means they have the permission, 0 or blank means they do not). The following properties are returned by the user_perms property. A value of 1 indicates true, a 0 or blank indicates false:
 
* user_perms (permissions assigned to the user, 1 means they have the permission, 0 or blank means they do not). The following properties are returned by the user_perms property. A value of 1 indicates true, a 0 or blank indicates false:
 
** timeTracking (whether or not user is authorized to track time)
 
** timeTracking (whether or not user is authorized to track time)
Line 140: Line 513:
 
** autoBreak (whether or not breaks have been automated)
 
** autoBreak (whether or not breaks have been automated)
 
** autoTrack (whether or not the users time entries have been automated)
 
** autoTrack (whether or not the users time entries have been automated)
 +
** gpsTrack (whether or not the account has requested GPS tracking)
 
* user_data (all data tracked for the user). The following properties are returned by the user_data property:
 
* user_data (all data tracked for the user). The following properties are returned by the user_data property:
−
** idx
+
** idx (TimeMD assigned ID)
−
** user
+
** user (users username)
−
** fstName
+
** fstName (users first name)
−
** lstName
+
** lstName (users last name)
−
** email
+
** email (users email address)
−
** status
+
** status (users status. 10 = Active, 90 = In-active)
−
** empNum
+
** empNum (users employee number)
−
** timeNum
+
** timeNum (users time clock number)
−
** dtHire
+
** dtHire (date hired in unix time)
−
** lastLogin
+
** lastLogin (date last logged into the system in unix time)
−
** dtCreated
+
** dtCreated (date users account was created)
−
** user_perms
+
** user_perms (full list of user permissions - only applicable to manager accounts)
−
* lang_settings
+
* lang_settings (language settings associated with this users's account). The following properties are returned by the lang_settings property:
−
** location
+
** location (the word for Location)
−
** department
+
** department (the word for Department)
−
** job
+
** job (the word for Job)
−
** task
+
** task (the word for Task)
−
** budget
+
** budget (the word for Budget)
−
** shift
+
** shift (the word for Shift)
 +
* all_users (complete list of all active employee accounts)
 
* tz (timezone)
 
* tz (timezone)
 +
* excessive_time_flag (The value for which if exceeded, the time entry is flagged as possibly tracking too much time.)
 +
 +
==== Time Entry ====
 +
* clocked_in (whether or not the user is clocked in. If used and if the user is clocked in, the clocked_in_data property is automatically returned.)
 +
* on_break (whether or not the user is on break. If used and if the user is on break, the on_break_data propert is automatically returned.)
 +
 +
==== Location, Department, Job, and Task Code Lists ====
 +
* all_locs (complete list of all locations assigned to client account)
 +
* all_depts (complete list of all departments including their associated location)
 +
* depts (complete list of all departments assigned to the use who's ID is being passed to the method)
 +
* all_jobs (complete list of all jobs assigned to client account)
 +
* jobs (complete list of all jobs assigned to the user who's ID is being passed to the method)
 +
* all_tasks (complete list of all tasks assigned to client account)
 +
 +
<b>Examples</b>
 +
* For example, if you want to get the properties fname, lname and clocked_in. Your URL would look like this:
 +
<pre>
 +
https://login.timemd.com/login/api.php?api_key=XXXXX_1536687004&user_idx=XXXX&property=fname|lname|clocked_in
 +
</pre>
 +
 +
<b>Output</b>
 +
* The output will be just the requested properties associated with the User ID passed to the method.
 +
<pre>
 +
<result>
 +
  <status>ok</status>
 +
  <message>
 +
    successfully retrieved properties: [fname|lname|clocked_in]
 +
  </message>
 +
  <clocked_in>1</clocked_in>
 +
  <clocked_in_data></clocked_in_data>
 +
  <fname>Bob</fname>
 +
  <lname>Smith</lname>
 +
</result>
 +
</pre>
 +
 +
== Misc. Actions ==
 +
=== Acknowledging Messages From Messanger Module ===
 +
Use this action to acknowledge that a message has been read in order to hide it from appearing again.
 +
 +
<b>Action</b>
 +
* message_read
 +
 +
<b>Parameters</b>
 +
{| border="1" cellspacing="0" cellpadding="2"
 +
|-
 +
!scope="col"| Parameter
 +
!scope="col"| Required
 +
!scope="col"| Description
 +
|-
 +
!scope="row"| api_key
 +
| Yes
 +
| See Register a Device section for details.
 +
|-
 +
!scope="row"| user_idx
 +
| Yes
 +
| The ID of the user acknowledging the message.
 +
|-
 +
!scope="row"| message_idx
 +
| Yes
 +
| The ID of the message being acknowledged.
 +
|}
 +
 +
<b>Output</b>
 +
* The ''status'' field will either be 'ok' or 'fail''. On 'fail' a ''message'' field will explain why.

Latest revision as of 14:05, 15 June 2023

Overview

Getting Started

  • First you'll need to authenticate the device you are using.
  • Even though each TimeMD account has a unique "Access URL" (or "Client URL"). You'll use our dedicated API URL for all calls to the server. In this case the URL is ‘login.timemd.com’.

What You Should Know First

  • TimeMD.com uses a REST interface for our API. REST is a simple format that allows you to make queries by constructing a URI containing variables and values and submitting to our API web page. The server responds with XML or JSON output containing the information that you requested.
  • Each API request is composed of two parts. An action and variables for that action. Additionally, all API calls (with the exception of register_device) require an api_key parameter that proves you are logged in. Normally you won't have to worry about this though, since our PHP class handles authentication for you.
  • All API output is returned in JSON format unless you add the output_format=xml option to your requests. All API requests will include a status field with a value of either ‘ok’ or ‘fail’. If the status is 'ok' there will also be a field named ‘message’ with more details. If the status is 'fail' there will also be an element named 'message' with more details.
  • We recommend using HTTPS for all API requests to our Access URL
  • GET vs. POST. Our API reads your actions and parameters from both GET and POST data. While examples below show parameters being posted via GET, it will work equally well if some (or all) of the parameters are passed as POST data.

API Actions

To register a device, your first login with a company's primary account login. You must pass the action ‘regiser_device’, and you must include the company's username and password:

In return you will get the accounts API Key. You must include the given key for all subsequent API calls related to that device (i.e. clock_out, clock_in, etc.) See "Authentication" section below for more information regarding the action, "register_device". 

<result>
 <status>ok</status>
 <message>The device has been successfully registered</message>
 <api_key>28150_1536687004</api_key>
</result>

When you receive a status of 'fail' from any API action, you'll also be given a message. For example: 

<result>
   <status>fail</status>
   <message>Login credentials not recognized</message>
</result>

When you receive a status of 'followup' from any API action, you'll also be given a message to display to the user. For example: 

<result>
   <status>followup</status>
   <message>Where you injured on the job today?</message>
</result>

Authentication

Registering A Device

This is required before any subsequent API actions can be placed. Upon successful authentication, you will receive the accounts API Key. This should be saved on the device.

Action

  • register_device

Parameters

Parameter Required Description
username Yes The username of the account to be registered.
password Yes The password of the account to be registered.

Output

  • The status field will either be 'ok' or 'fail'. On 'fail' a message field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.

Tracking Time

Clocking In

Usually called Clocking-in', punching the clock or starting a timer, this call lets you start tracking time for a user.

Action

  • clock_in

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details.
user_idx Yes The TimeMD assigned ID of the user you would like to click in with.
dept_idx Maybe The TimeMD assigned ID of the department the user is to be clocked in under. If this parameter is not passed, the system will assume the primary department is being used.
job_idx Maybe The TimeMD assigned ID of the job the user is to be clocked in under. If this parameter is not passed, the system will assume the primary job is being used “If” job tracking is required.
task_idx Maybe The TimeMD assigned ID of the taks the user is to be clocked in under.
photo_bin Maybe The binary data of the photograph taken during the clock_in action. This is required on devices with a camera.
gps_lat Maybe The latitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.
gps_lon Maybe The longitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.

Output

  • The status field will either be 'ok' or 'fail'. On 'fail' a message field will explain why.

Clocking Out

Clock out a user. Also called punching out or stopping a timer.

Action

  • clock_out

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details.
time_idx Yes The TimeMD assigned ID of the time entry the user is clocking out from.
dept_idx Yes The TimeMD assigned department ID. If different then the department ID saved to existing time entry, system will automatically clock user in under the new ID.
job_idx Maybe The TimeMD assigned job ID. If passed and if different then the job ID saved to time entry, system will automatically clock user in under the new ID.
task_idx Maybe The TimeMD assigned task ID. If passed and if different then the task ID saved to time entry, system will automatically clock user in under the new ID.
photo_bin Maybe The binary data of the photograph taken during the clock_out action. This is required on devices with a camera.
gps_lat Maybe The latitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.
gps_lon Maybe The longitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.

Output

  • The status field will either be 'ok' or 'fail'. On 'fail' a message field will explain why.

Starting A Break

This call lets you start a break for a user.

Action

  • start_break

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details.
user_idx Yes The TimeMD assigned ID of the user you would like to start a break with.
time_idx Yes The TimeMD assigned ID of the time entry the user is starting their break from.

Output

  • The status field will either be 'ok' or 'fail. On 'fail' a message field will explain why.

Ending A Break

This call lets you start a break for a user.

Action

  • end_break

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details.
user_idx Yes The TimeMD assigned ID of the user you would like to end a break with.
time_idx Yes The TimeMD assigned ID of the time entry the user is ending their break from.
time_break_idx Yes The TimeMD assigned ID of the break entry the user is ending from.

Output

  • The status field will either be 'ok' or 'fail. On 'fail' a message field will explain why.

Data Management

Adding Users

Used to add new employees to your account.

Action

  • custom_add_employee

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details
employee_id Yes The Employee ID of the employee being added
first_name Yes First name of the employee
last_name Yes Last name of the employee
cell_number Yes Cell number for the employee. Format (123)456-7890
employee_status Yes Employee status. 1 = Active. 0 = Inactive

Output

  • The status field will either be 'ok' or 'fail'. On 'fail' a message field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.

Updating Users

Used to add update employees.

Action

  • custom_update_employee

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details
employee_id Yes The Employee ID of the employee being updated
first_name No First name of the employee
last_name No Last name of the employee
cell_number No Cell number for the employee. Format (123)456-7890
employee_status No Employee status. 1 = Active. 0 = Inactive

Output

  • The status field will either be 'ok' or 'fail'. On 'fail' a message field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.

Adding Locations

Used to add new locations.

Action

  • custom_add_location

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details
location_id Yes The Location ID of the location being added
location_name Yes Name of the location
location_time_zone No Time zone of the location
location_address1 No Address of the location
location_address2 No Address of the location
location_city No City of the location
location_state No State of the location
location_zip No Zip of the location
location_geo_address No GPS full address of the location in the following format: street, city, state, zip, country
location_geo_lat No Latitude of the location in decimal form
location_geo_lon No Longitude of the location in decimal form
location_geo_radius No Geo fence radius of the location
location_geo_active No Status of the geo fence: 1 = Active, 0 = Inactive

Output

  • The status field will either be 'ok' or 'fail'. On 'fail' a message field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.

Updating Locations

Used to update an existing locations.

Action

  • custom_update_location

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details
location_id Yes The Location ID of the location being updated
location_name Yes Name of the location
location_time_zone No Time zone of the location
location_address1 No Address of the location
location_address2 No Address of the location
location_city No City of the location
location_state No State of the location
location_zip No Zip of the location
location_geo_address No GPS full address of the location in the following format: street, city, state, zip, country
location_geo_lat No Latitude of the location in decimal form
location_geo_lon No Longitude of the location in decimal form
location_geo_radius No Geo fence radius of the location
location_geo_active No Status of the geo fence: 1 = Active, 0 = Inactive

Output

  • The status field will either be 'ok' or 'fail'. On 'fail' a message field will explain why. On 'ok', the action will also return the API Key which is required for all subsequent action calls.

Read-Only Information

Retrieving Properties

If you want to retrieve a property for a user, such as clocked_in or full_name, you may do so via the “get” API action. The following parameters are available:

Action

  • get

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details.
user_idx No If provided, the method will return data specific to that user. If not provided, method will return data specific to the account the API Key belongs too.
device_id No If provided, the method will return data specific to that device. If not provided, method will return data specific to the account the API Key belongs too.
property Yes The property or properties that you would like to retrieve. You may specify multiple properties at once, just provide them separated by a pipe character, without spaces.

The following properties are available for retrieval via the get action:

Account Related Properties

  • username (username)
  • fname (fist name)
  • lname (last name)
  • full_name (full name of the user)
  • emp_num (employee number)
  • company_name (company name)
  • messages (any messages that need to be reviewed by the user.)
  • primary_dept (the name of the primary department assigned to the user. If used, the primary_dept_data property is automatically returned. The following properties are returned by the primary_dept_data property:
    • idx (TimeMD assigned ID)
    • name (name of the department)
    • location (name of the department is assigned too)
  • primary_job (the name of the primary job assigned to the user. If used, the primary_job_data property is automatically returned. The following properties are returned by the primary_job_data property:
    • idx (TimeMD assigned ID)
    • jobIdx (parent job ID)
    • name (name of job)
    • jobId (User assigned job ID)
  • user_perms (permissions assigned to the user, 1 means they have the permission, 0 or blank means they do not). The following properties are returned by the user_perms property. A value of 1 indicates true, a 0 or blank indicates false:
    • timeTracking (whether or not user is authorized to track time)
    • displayJobs (whether or not jobs should be displayed)
    • displayTasks (whether or not tasks should be displayed)
    • autoBreak (whether or not breaks have been automated)
    • autoTrack (whether or not the users time entries have been automated)
    • gpsTrack (whether or not the account has requested GPS tracking)
  • user_data (all data tracked for the user). The following properties are returned by the user_data property:
    • idx (TimeMD assigned ID)
    • user (users username)
    • fstName (users first name)
    • lstName (users last name)
    • email (users email address)
    • status (users status. 10 = Active, 90 = In-active)
    • empNum (users employee number)
    • timeNum (users time clock number)
    • dtHire (date hired in unix time)
    • lastLogin (date last logged into the system in unix time)
    • dtCreated (date users account was created)
    • user_perms (full list of user permissions - only applicable to manager accounts)
  • lang_settings (language settings associated with this users's account). The following properties are returned by the lang_settings property:
    • location (the word for Location)
    • department (the word for Department)
    • job (the word for Job)
    • task (the word for Task)
    • budget (the word for Budget)
    • shift (the word for Shift)
  • all_users (complete list of all active employee accounts)
  • tz (timezone)
  • excessive_time_flag (The value for which if exceeded, the time entry is flagged as possibly tracking too much time.)

Time Entry

  • clocked_in (whether or not the user is clocked in. If used and if the user is clocked in, the clocked_in_data property is automatically returned.)
  • on_break (whether or not the user is on break. If used and if the user is on break, the on_break_data propert is automatically returned.)

Location, Department, Job, and Task Code Lists

  • all_locs (complete list of all locations assigned to client account)
  • all_depts (complete list of all departments including their associated location)
  • depts (complete list of all departments assigned to the use who's ID is being passed to the method)
  • all_jobs (complete list of all jobs assigned to client account)
  • jobs (complete list of all jobs assigned to the user who's ID is being passed to the method)
  • all_tasks (complete list of all tasks assigned to client account)

Examples

  • For example, if you want to get the properties fname, lname and clocked_in. Your URL would look like this:
https://login.timemd.com/login/api.php?api_key=XXXXX_1536687004&user_idx=XXXX&property=fname|lname|clocked_in

Output

  • The output will be just the requested properties associated with the User ID passed to the method.
<result>
  <status>ok</status>
  <message>
    successfully retrieved properties: [fname|lname|clocked_in]
  </message>
  <clocked_in>1</clocked_in>
  <clocked_in_data></clocked_in_data>
  <fname>Bob</fname>
  <lname>Smith</lname>
</result>

Misc. Actions

Acknowledging Messages From Messanger Module

Use this action to acknowledge that a message has been read in order to hide it from appearing again.

Action

  • message_read

Parameters

Parameter Required Description
api_key Yes See Register a Device section for details.
user_idx Yes The ID of the user acknowledging the message.
message_idx Yes The ID of the message being acknowledged.

Output

  • The status field will either be 'ok' or 'fail. On 'fail' a message field will explain why.
Retrieved from "http://help.timemd.com/index.php?title=API&oldid=542"