TimeWellScheduled API Documentation

GETTING STARTED

1. Introduction
2. Getting Started
3. Authentication & Security
4. Request Format
5. Response Format
6. Modules

7. Optional Parameters
8. Single Sign-On (SSO)
9. Error Handling
10. Support

1. Introduction

The TimeWellScheduled API allows developers to securely integrate scheduling, time tracking, payroll, and HR features into their applications. All requests are made over HTTPS and return structured data in either JSON or XML formats.

2. Getting Started

Before you begin, you’ll need an API Key and Company ID.
Follow the API key setup guide to generate your API key.

API URL:

 

3. Authentication & Security

  • Application ID [appid] – provided by us API key setup guide
  • Company ID [c] – your unique company. It can be found here
  • Module [module] – the module being called
  • Encryption: All passwords are stored using bCrypt

 You’ll need to hash employee credentials with the company-specific salt provided during authentication. For more on bCrypt, read this.

4. Request Format

All requests use the GET method with parameters passed in the query string.

Example:

GET /?appid={AppID}&c={CompanyID}&module=verify

Required Parameters:

appid – Your Application ID
c – Company ID
module – API module to call

 

5. Response Format

Responses return structured results in JSON or XML (some calls are return JSON, some XML).

Example JSON Response:

 

{
"success": 1,
"ontime": 1,
"message": "Your action has been recorded successfully"
}

6. Modules

verify

Retrieves company information and employee list.

Endpoint URL:

<API URL>/response.asp

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=verify

Example Response:

<?xml version=”1.0”?>
 <response>
 <success>1</success>
 <ontime>1</ontime>
 <message>
 	<employees>
 		<employee>
 		<name>Bob Robertson</name>
 		<id>12345</id>
 		</employee>
 		<employee>
 		<name>Jane Johnson</name>
 		<id>abc123</id>
 		</employee>
 		<employee>
 		<name>Bill Smith</name>
 		<id>995jk</id>
 		</employee>
 	</employees>
 	<branding logo="https://url_to_logo/MainLogo.png">Your Company Here</branding>
 	<bcryptSalt>yourKey</bcryptSalt>
 </message>
 </response>

begin

Records the start of an employee’s shift.

Endpoint URL:

<API URL>/response.asp

Additional Parameters:

U – punch code
P – employee password (in bCrypt)
Year – the year the action is taking place
Month – the month the action is taking place
Day – the day the action is taking place
Hour – the hour the action is taking place
Minute – the minute the action is taking place
Second - the second the action is taking place

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=begin&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=16&Minute=0&Second=34

Example Response: 

<?xml version=”1.0”?>
 <response>
 	<success>1</success>
 	<ontime>1</ontime>
 	<message>Your action has been recorded successfully. You have 12 unread message(s) in your Inbox.</message>
 </response>

end

Records the end of an employee’s shift.

Endpoint URL:

<API URL>/response.asp

Additional Parameters:

U – punch code
P – employee password (in bCrypt)
Year – the year the action is taking place
Month – the month the action is taking place
Day – the day the action is taking place
Hour – the hour the action is taking place
Minute – the minute the action is taking place
Second - the second the action is taking place

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=end&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=19&Minute=05&Second=25

Example Response: 

<?xml version=”1.0”?>
 <response>
 	<success>0</success>
 	<ontime>0</ontime>
 	<message>It is too early for you to EXIT</message>
 	<watchdog>
 		<message>Select a reason.</message>
 		<reasons>
 			<reason ID="2233">Accident de route</reason>
 			<reason ID="153">Car problems</reason>
 			<reason ID="157">Computer issues</reason>
 			<reason ID="1482">Default reason code</reason>
 			<reason ID="159">Finished early</reason>
 			<reason ID="154">Not feeling well</reason>
 			<reason ID="156">Other (Please explain)</reason>
 			<reason ID="1983">Personal emergency</reason>
 			<reason ID="2231">Rendez-vous chez le medecin</reason>
 			<reason ID="158">Traffic</reason>
 		</reasons>
 	</watchdog>
 </response>

Since the request was not successful and a watchdog event was triggered. We need to send the same request again with the extra parameter REASON ID enclosed in the tag.

Example request:

GET /?appid={AppID}&c={CompanyID}&module=end&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=19&Minute=05&Second=25&reason={reason ID}

Example Response:

<?xml version=”1.0”?>
 <response>
 	<success>1</success>
 	<ontime>1</ontime>
 	<message>Your action has been recorded successfully.</message>
 </response>

break

Records the start or end of a break.

Endpoint URL:

<API URL>/response.asp

Additional Parameters:

U – punch code
P – employee password (in bCrypt)
Year – the year the action is taking place
Month – the month the action is taking place
Day – the day the action is taking place
Hour – the hour the action is taking place
Minute – the minute the action is taking place
Second - the second the action is taking place

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=break&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=18&Minute=15&Second=09

Example Response:

<?xml version=”1.0”?>
 <response>
 	<success>1</success>
 	<ontime>1</ontime>
 	<message>Your action has been recorded successfully.</message>
 </response>

meal

Records the start or end of a meal period.

Endpoint URL:

<API URL>/response.asp

Additional Parameters:

U – punch code
P – employee password (in bCrypt)
Year – the year the action is taking place
Month – the month the action is taking place
Day – the day the action is taking place
Hour – the hour the action is taking place
Minute – the minute the action is taking place
Second - the second the action is taking place

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=meal&u={punchCode}&p={bCryptPassword}&Year=2025&Month=9&Day=22&Hour=17&Minute=08&Second=25

Example Response: 

<?xml version=”1.0”?>
 <response>
 	<success>0</success>
 	<ontime>0</ontime>
 	<message>This action cannot be done. Your schedule does not allow any MEALS</message>
 </response>

 

schedule_list

Retrieves schedules for an employee within a given date range.

Endpoint URL:

<API URL>/response_json.asp

Additional Parameters:

StartDate – the starting date range
EndDate – the end date range

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=schedule_list&u={punchCode}&StartDate=2025-09-01&EndDate= 2025-09-02

Example Response:

{
"success": 1,
"schedules": [
{"date": "2025-09-01", "time": "9:00-17:00", "dept": "Office"},
{"date": "2025-09-02", "time": "9:00-17:00", "dept": "Office"}
]
}

 

employee_list

Retrieves all active employees.

Endpoint URL:

<API URL>/response_json.asp

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=employee_list

Example Response:

{
"success": 1,
"employees": [
{"id": "001", "name": "Alice Johnson"},{"id": "002", "name": "Mark Smith"}
]
}

 

 

absence_list

Retrieves employee absences within a given date range.

Endpoint URL:

<API URL>/response_json.asp

Additional Parameters:

StartDate – the starting date range
EndDate – the end date range

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=absence_list&StartDate=2025-09-01&EndDate=2025-09-30

Example Response:

{
"success": 1,
"absences": [
{"employee": "John Doe", "from": "2025-09-10", "to": "2025-09-12", "type": "Vacation"}
]
}

 

payroll_list

Retrieves payroll details for a date range.

Endpoint URL:

<API URL>/response_json.asp

Additional Parameters:

StartDate – the starting date range
EndDate – the end date range

Example Request:

GET /?appid={AppID}&c={CompanyID}&module=payroll_list&StartDate=2025-09-01&EndDate=2025-09-15

Example Response:

{
"success": 1,
"payroll": [
{"employee": "Anne Robinson", "totalRT": 40, "totalOT": 5},
{"employee": "Sam Smith", "totalRT": 38, "totalOT": 0}
]
}

 

who_is_working

Retrieves list of all employees scheduled to work today.

Endpoint URL:

<API URL>/response_json.asp

Additional Parameters:

Date – the date to view the schedules for

Example Request:

GET /?appid={AppID}&c={CompanyID}&module= who_is_working&Date=2025-09-25

Example Response:

{
    "schedules": [
        {
            "employeeName": "Chester Field",
            "departmentName": "Widget Assembly",
            "departmentCode": "WA",
            "shiftStartDate": "October 28, 2025",
            "shiftStartTime": "7:00a",
            "shiftEndDate": "October 28, 2025",
            "shiftEndTime": "4:30p",
            "status": "On Duty"
        }
    ],
    "displayDate": "October 28, 2025",
}
}

 

7. Optional Parameters

file – Attach a photo with punch actions
lat/lng – Pass geolocation coordinates
ip – Restrict actions to registered IPs
reason – Supply 'watchdog' reasons when required

8. Single Sign-On (SSO)

TimeWellScheduled supports SSO, allowing users to log in directly via a secure URL. Required

parameters: appid, c, userEmail, timestamp, hash. Contact support to confirm your data center URL.

9. Error Handling

API responses include a success flag and descriptive messages. – success = 1 → Request successful –

success = 0 → Error (see message or watchdog response for details)

10. Support

If you encounter issues: Email: [email protected] Phone: 1-877-689-7977