Difference between revisions of "API"
From TimeMD Help
(→Clocking In) |
(→Clocking In) |
||
| Line 52: | Line 52: | ||
| See Register a Device section for details. | | See Register a Device section for details. | ||
|- | |- | ||
| − | !scope="row"| | + | !scope="row"| user_idx |
| − | | | + | | Yes |
| − | | | + | | The TimeMD assigned ID of the user you would like to click in with. |
|- | |- | ||
| − | !scope="row | + | !scope="row"| 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.} |
Revision as of 17:38, 10 February 2012
Contents
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>
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.} |
