API

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:

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

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

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		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		The TimeMD assigned ID of the taks the user is to be clocked in under.
gps_lat		The latitude coordinate of the device if available and if the client has requested for GPS tracking coordinates.
gps_lon		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', 'fail' or 'followup'. On 'fail' a message field will explain why. On 'followup', a message field will contain the content that should be displayed to the user. The message displayed to the user should also contain a "Yes/No" option for the user to respond too. See "follow_up" action for more details.

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.

Output

• The status field will either be 'ok', 'fail' or 'followup'. On 'fail' a message field will explain why. On 'followup', a message field will contain the content that should be displayed to the user. The message displayed to the user should also contain a "Yes/No" option for the user to respond too. See "follow_up" action for more details.

Follow Up

This action is used to respond to a "followup" response from a previous action.

Action

• follow_up

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 responding the follow-up question too.
response	Yes	The response to the Yes/No question from the follow-up. 1 = yes. 0 = No

Output

• The status field will either be 'ok', 'fail' or 'followup'. On 'fail' a message field will explain why. On 'followup', a message field will contain the content that should be displayed to the user. The message displayed to the user should also contain a "Yes/No" option for the user to respond too. See "follow_up" action for more details.

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.
property	Yes	), 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)
• 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)
• 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)
• tz (timezone)