TimeStation - TimeStation API V1

TimeStation API V1

Introduction
The TimeStation API allows you to programmatically access and modify data in your TimeStation account. The TimeStation API is organized around REST, it has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. The REST endpoint URL for the TimeStation API is:

https://api.mytimestation.com/v1/

Authentication
The TimeStation API uses API keys to authenticate requests. To request an API Key for your account, please send an eMail to Support@MyTimeStation.com.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer 4uahz4f7cvj29x63ew65vw3yf9p8rpeg" instead of -u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

curl https://api.mytimestation.com/v1/employees \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:

# The colon prevents curl from asking for a password.

Errors
TimeStation uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, etc.), and codes in the 5xx range indicate an error with TimeStation's servers.

200 OK - Everything worked as expected.
400 Bad Request - Often missing a required parameter.
401 Unauthorized - No valid API key provided.
402 Request Failed - Parameters were valid but request failed.
404 Not Found - The requested item doesn't exist.
500, 502, 503, 504 Server errors - something went wrong on TimeStation's end.

Not all errors map cleanly onto HTTP response codes, however. When an error occurs and more details are available about this error, that information can be found in the JSON response body as seen in the example below:

{ "error": { "error_code": "401", "error_text": "Invalid API Key" } }

Versioning
When we make API changes that may affect compatibility with earlier versions we publish a new version of the API. The latest API version is v1.2, this document is for version 1 which is an older version. The API version is reflected in the REST endpoint URL.

You can find the documentation for other versions of the API below:

Rate Limiting
To ensure optimal performance for all API users, there's a limit of 5,000 API requests per TimeStation account per day.

Employees

List Employees
Returns an array of all the existing employees

GEThttps://api.mytimestation.com/v1/employees

curl https://api.mytimestation.com/v1/employees \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:

{ "employees": [ { "employee_id": "emp_ngdzkmpmk2", "name": "Alex Mahone", "primary_department": "Sales", "primary_department_id": "dpt_1x95r1zkqf", "current_department": "Sales", "current_department_id": "dpt_1x95r1zkqf", "status": "in", "custom_employee_id": "EMP-0001", "hourly_rate": "15.00", "pin": "1111", "card_number": "00001", "card_qr_code": "8101372308680381859773485135341" }, { "employee_id": "emp_ekj8x0q7p4", "name": "Angela Martin", "title": "Payroll Manager", "primary_department": "Accounting", "primary_department_id": "dpt_241x9xqel0", "current_department": "Sales", "current_department_id": "dpt_1x95r1zkqf", "status": "out", "custom_employee_id": "EMP-0002", "pin": "2222", "card_number": "00002", "card_qr_code": "810137230868939153673412038795", "custom_fields": { "Phone Number": "(212) 555-1234", "Start Date": "08/15/2023" } }, { "employee_id": "emp_dp246d0wj3", "name": "Michael Scott", "title": "Office Boss", "primary_department": "Management", "primary_department_id": "dpt_rq7en39fxn", "current_department": "Management", "current_department_id": "dpt_rq7en39fxn", "status": "out", "card_number": "00003", "card_qr_code": "8101377322767786421574045082934" } ] }

Single Employee
Returns the details of a single employee

GEThttps://api.mytimestation.com/v1/employees/{employee_id}

Parameter	Location	Description
employee_id	URL	REQUIRED TimeStation Employee ID

curl https://api.mytimestation.com/v1/employees/emp_ekj8x0q7p4 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:

{ "employee": { "employee_id": "emp_ekj8x0q7p4", "name": "Angela Martin", "title": "Payroll Manager", "primary_department": "Accounting", "primary_department_id": "dpt_241x9xqel0", "current_department": "Sales", "current_department_id": "dpt_1x95r1zkqf", "status": "out", "custom_employee_id": "EMP-0002", "pin": "2222", "card_number": "00002", "card_qr_code": "810137230868939153673412038795", "custom_fields": { "Phone Number": "(212) 555-1234", "Start Date": "08/15/2023" } } }

Create Employee
Creates a new employee.

POSThttps://api.mytimestation.com/v1/employees

Parameter	Location	Description
name	Body	REQUIRED Employee Name
department_id	Body	Assign employee to an exisiting primary department. REQUIRED Either department_id or department_name must be supplied.
department_name	Body	Assign employee to a department named department_name. Will either create a new department named department_name or use an existing department if a department already exists with the name department_name. REQUIRED Either department_id or department_name must be supplied.
custom_employee_id	Body	An optional second Employee ID you can set to associate the employee with an entity in another system.
title	Body	Employee Title
hourly_rate	Body	Hourly Rate
pin	Body	4-Digit PIN
custom_fields[field_name]	Body	Set one or more employee custom fields. field_name represents the name of an existing employee custom field.

curl https://api.mytimestation.com/v1/employees \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d name="Angela Martin" \
-d department_name="Accounting" \
-d custom_employee_id="EMP-0002" \
-d title="Payroll Manager" \
-d hourly_rate="25.00" \
-d pin="2222"
-d custom_fields[Phone Number]="(212) 555-1234"
-d custom_fields[Start Date]="08/15/2023"

{ "employee": { "employee_id": "emp_ekj8x0q7p4" } }

Update Employee
Updates an existing employee using the fields provided.

Note: Please be careful when updating an employee, as the existing employee will be replaced by the request body. Any fields not provided will be cleared.

PUThttps://api.mytimestation.com/v1/employees/{employee_id}

Parameter	Location	Description
employee_id	URL	REQUIRED TimeStation Employee ID
name	Body	REQUIRED Employee Name
department_id	Body	Assign employee to an exisiting primary department. REQUIRED Either department_id or department_name must be supplied.
department_name	Body	Assign employee to a department named department_name. Will either create a new department named department_name or use an existing department if a department already exists with the name department_name. REQUIRED Either department_id or department_name must be supplied.
custom_employee_id	Body	An optional second Employee ID you can set to associate the employee with an entity in another system.
title	Body	Employee Title
hourly_rate	Body	Hourly Rate
pin	Body	4-Digit PIN
custom_fields[field_name]	Body	Set one or more employee custom fields. field_name represents the name of an existing employee custom field.
convert_primary_department	Query String	If set to true and the primary department is changed, the previous primary department will be kept as a secondary department. This parameter only applies to the current API request.

curl https://api.mytimestation.com/v1/employees/emp_ekj8x0q7p4 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d name="Angela Martin" \
-d department_name="Accounting" \
-d custom_employee_id="EMP-0002" \
-d title="Payroll Manager" \
-d hourly_rate="25.00" \
-d pin="2222" \
-d custom_fields[Phone Number]="(212) 555-1234"
-d custom_fields[Start Date]="08/15/2023"
-X PUT

{ "employee": { "employee_id": "emp_ekj8x0q7p4" } }

Check-Out Employee
Closes the current open shift for an employee

PUThttps://api.mytimestation.com/v1/employees/{employee_id}/check-out

Parameter	Location	Description
employee_id	URL	REQUIRED TimeStation Employee ID
time_out	Body	Optional check-out date & time. If ommited, the shift is closed at the current time, using the UTC offset from the associated check-in. Format: ISO-8601 with UTC offset (YYYY-MM-DDTHH:MM:SSZ)
notes	Body	Notes
time_deduction_minutes	Body	Number of minutes to deduct from the shift. Overrides the automatic time deduction rules for this shift.

curl https://api.mytimestation.com/v1/employees/emp_ekj8x0q7p4/check-out \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d time_out="2023-07-12T17:00-05:00" \

{ "employee": { "employee_id": "emp_ekj8x0q7p4" } }

Delete Employee
Deletes an existing employee

DELETEhttps://api.mytimestation.com/v1/employees/{employee_id}

Parameter	Location	Description
employee_id	URL	REQUIRED TimeStation Employee ID

curl https://api.mytimestation.com/v1/employees/emp_ekj8x0q7p4 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-X DELETE

{ "employee": { "employee_id": "emp_ekj8x0q7p4" } }

Departments

List Departments
Returns an array of all the existing departments

GEThttps://api.mytimestation.com/v1/departments

curl https://api.mytimestation.com/v1/departments \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:

{ "departments": [ { "department_id": "dpt_241x9xqel0", "name": "Accounting", "type": "Department", "employees_total": "2", "employees_primary": "2", "employees_in": "0" }, { "department_id": "dpt_1x95r1zkqf", "name": "Sales", "type": "Department", "employees_total": "5", "employees_primary": "4", "employees_in": "1" }, { "department_id": "dpt_rq7en39fxn", "name": "Management", "type": "Department", "employees_total": "1", "employees_primary": "1", "employees_in": "0" } ] }

Single Department
Returns the details of a single department

GEThttps://api.mytimestation.com/v1/departments/{department_id}

Parameter	Location	Description
department_id	URL	REQUIRED TimeStation Department ID

curl https://api.mytimestation.com/v1/departments/dpt_1x95r1zkqf \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:

{ "department": { "department_id": "dpt_1x95r1zkqf", "name": "Sales", "type": "Department", "employees_total": "5", "employees_primary": "4", "employees_in": "1" } }

Create Department
Creates a new department.

POSThttps://api.mytimestation.com/v1/departments

Parameter	Location	Description
name	Body	REQUIRED Department Name

curl https://api.mytimestation.com/v1/departments \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d name="Sales"

{ "department": { "department_id": "dpt_1x95r1zkqf" } }

Update Department
Updates an existing department using the fields provided.

Note: Please be careful when updating a department, as the existing department will be replaced by the request body. Any fields not provided will be cleared.

PUThttps://api.mytimestation.com/v1/departments/{department_id}

Parameter	Location	Description
department_id	URL	REQUIRED TimeStation Department ID

curl https://api.mytimestation.com/v1/departments/dpt_1x95r1zkqf \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d name="Sales" \
-X PUT

{ "department": { "department_id": "dpt_1x95r1zkqf" } }

Delete Department
Deletes an existing department.

DELETEhttps://api.mytimestation.com/v1/departments/{department_id}

Parameter	Location	Description
department_id	URL	REQUIRED TimeStation Department ID

curl https://api.mytimestation.com/v1/departments/dpt_1x95r1zkqf \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-X DELETE

{ "department": { "department_id": "dpt_1x95r1zkqf" } }

Shifts

A shift is a record of the start and end times for a single work shift for an employee. Each shift is associated with a department and may include a time deduction for breaks. Employees can have multiple shifts throughout the day.

List Shifts
Returns an array of the last 2,000 shifts for an employee between start_date and end_date

Note:total_minutes represents the calculated length of the shift based on any time-rounding rules defined in the account.

GEThttps://api.mytimestation.com/v1/shifts

Parameter	Location	Description
employee_id	Query String	REQUIRED TimeStation Employee ID
start_date	Query String	Start Date Format: ISO-8601 (YYYY-MM-DD)
end_date	Query String	End Date Format: ISO-8601 (YYYY-MM-DD)

curl https://api.mytimestation.com/v1/shifts?employee_id=emp_ekj8x0q7p4&start_date=2023-07-01&end_date=2023-07-15 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:

{ "shifts": [ { "shift_id": "shft_rgnw7mr7q2", "employee_id": "emp_ekj8x0q7p4", "department_id": "dpt_1x95r1zkqf", "total_minutes": "480", "notes": "User forgot to check-in", "in": { "time": "2023-07-12T09:00:00-05:00", "device": "TimeStation-05", "location": { "coordinates": { "latitude": "40.723017", "longitude": "-73.999116" } } }, "out": { "time": "2023-07-12T17:00:00-05:00", "device": "TimeStation-05", "location": { "coordinates": { "latitude": "40.723017", "longitude": "-73.999116" } } } }, { "shift_id": "shft_8ovv567xl0", "employee_id": "emp_ekj8x0q7p4", "department_id": "dpt_1x95r1zkqf", "total_minutes": "195", "in": { "time": "2023-07-10T19:15:00-05:00" }, "out": { "time": "2023-07-10T22:30:00-05:00" } }, { "shift_id": "shft_0266lnv6er", "employee_id": "emp_ekj8x0q7p4", "department_id": "dpt_1x95r1zkqf", "total_minutes": "384", "in": { "time": "2023-07-06T08:05:15-05:00", "device": "TimeStation-05", "location": { "coordinates": { "latitude": "40.723017", "longitude": "-73.999116" } } }, "out": { "time": "2023-07-10T14:29:03-05:00", "device": "TimeStation-05", "location": { "coordinates": { "latitude": "40.723017", "longitude": "-73.999116" } } } } ] }

Single Shift
Returns the details of a single shift

Note: total_minutes represents the calculated length of the shift based on any time-rounding rules defined in the account.

GEThttps://api.mytimestation.com/v1/shifts/{shift_id}

Parameter	Location	Description
shift_id	URL	REQUIRED TimeStation Shift ID

curl https://api.mytimestation.com/v1/shifts/shft_rgnw7mr7q2 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:

{ "shift": { "shift_id": "shft_rgnw7mr7q2", "employee_id": "emp_ekj8x0q7p4", "department_id": "dpt_1x95r1zkqf", "total_minutes": "480", "in": { "time": "2023-07-12T09:00:00-05:00", "device": "TimeStation-05", "location": { "coordinates": { "latitude": "40.723017", "longitude": "-73.999116" } } }, "out": { "time": "2023-07-10T17:00:00-05:00", "device": "TimeStation-05", "location": { "coordinates": { "latitude": "40.723017", "longitude": "-73.999116" } } } } }

Create Shift
Creates a new shift.

POSThttps://api.mytimestation.com/v1/shifts

Parameter	Location	Description
employee_id	Body	REQUIRED TimeStation Employee ID
department_id	Body	REQUIRED TimeStation Department ID
time_in	Body	REQUIRED Check-in date & time Format: ISO-8601 with UTC offset (YYYY-MM-DDTHH:MM:SSZ)
time_out	Body	Check-out date & time. If ommited, an open shift is created. Format: ISO-8601 with UTC offset (YYYY-MM-DDTHH:MM:SSZ)
notes	Body	Notes
time_deduction_minutes	Body	Number of minutes to deduct from the shift. Overrides the automatic time deduction rules for this shift.

curl https://api.mytimestation.com/v1/shifts \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d employee_id="emp_ekj8x0q7p4" \
-d department_id="dpt_1x95r1zkqf" \
-d time_in="2023-07-12T09:00-05:00" \
-d time_out="2023-07-12T17:00-05:00" \
-d notes="User forgot to check-in" \

{ "shift": { "shift_id": "shft_rgnw7mr7q2" } }

Update Shift
Updates an existing shift using the fields provided.

Note: Please be careful when updating a shift, as the existing shift will be replaced by the request body. Any fields not provided will be cleared.

PUThttps://api.mytimestation.com/v1/shifts/{shift_id}

Parameter	Location	Description
shift_id	URL	REQUIRED TimeStation Shift ID
department_id	Body	REQUIRED TimeStation Department ID
time_in	Body	REQUIRED Check-in date & time Format: ISO-8601 with UTC offset (YYYY-MM-DDTHH:MM:SSZ)
time_out	Body	Check-out date & time. Can be ommited for an open shift. If the shift is already closed, then this paramerter is required. Format: ISO-8601 with UTC offset (YYYY-MM-DDTHH:MM:SSZ)
notes	Body	Notes
time_deduction_minutes	Body	Number of minutes to deduct from the shift. Overrides the automatic time deduction rules for this shift.

curl https://api.mytimestation.com/v1/shifts/shft_rgnw7mr7q2 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d department_id="dpt_1x95r1zkqf" \
-d time_in="2023-07-12T09:00-05:00" \
-d time_out="2023-07-12T17:00-05:00" \
-d notes="User forgot to check-in" \
-X PUT

{ "shift": { "shift_id": "shft_rgnw7mr7q2" } }

Close Shift
Closes an open shift.

PUThttps://api.mytimestation.com/v1/shifts/{shift_id}/close

Parameter	Location	Description
shift_id	URL	REQUIRED TimeStation Shift ID
time_out	Body	Optional check-out date & time. If ommited, the shift is closed at the current time, using the UTC offset from the associated check-in. Format: ISO-8601 with UTC offset (YYYY-MM-DDTHH:MM:SSZ)
notes	Body	Notes
time_deduction_minutes	Body	Number of minutes to deduct from the shift. Overrides the automatic time deduction rules for this shift.

curl https://api.mytimestation.com/v1/shifts/shft_rgnw7mr7q2/close \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d time_out="2023-07-12T17:00-05:00" \

{ "shift": { "shift_id": "shft_rgnw7mr7q2" } }

Delete Shift
Deletes an existing shift

DELETEhttps://api.mytimestation.com/v1/shifts/{shift_id}

Parameter	Location	Description
shift_id	URL	REQUIRED TimeStation Shift ID

curl https://api.mytimestation.com/v1/shifts/shft_rgnw7mr7q2 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-X DELETE

{ "shift": { "shift_id": "shft_rgnw7mr7q2" } }