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.
Authenticated Request
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 Response
{ "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:
- Version 0.1
- Version 1.1
- Version 1.2
To ensure optimal performance for all API users, there's a limit of 5,000 API requests per TimeStation account per day.
List Employees
Returns an array of all the existing employees
GEThttps://api.mytimestation.com/v1/employees
List Employees Request
curl https://api.mytimestation.com/v1/employees \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:
List Employees Response
{ "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 |
Single Employee Request
curl https://api.mytimestation.com/v1/employees/emp_ekj8x0q7p4 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:
Single Employee Response
{ "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. |
Create Employee Request
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"
Create Employee Response
{ "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. |
Update Employee 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
Update Employee Response
{ "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. |
Check-Out Employee Request
curl https://api.mytimestation.com/v1/employees/emp_ekj8x0q7p4/check-out \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d time_out="2023-07-12T17:00-05:00" \
Check-Out Employee Response
{ "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 |
Delete Employee Request
curl https://api.mytimestation.com/v1/employees/emp_ekj8x0q7p4 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-X DELETE
Delete Employee Response
{ "employee": { "employee_id": "emp_ekj8x0q7p4" }}
List Departments
Returns an array of all the existing departments
GEThttps://api.mytimestation.com/v1/departments
List Departments Request
curl https://api.mytimestation.com/v1/departments \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:
List Departments Response
{ "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 |
Single Department Request
curl https://api.mytimestation.com/v1/departments/dpt_1x95r1zkqf \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:
Single Department Response
{ "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 |
Create Department Request
curl https://api.mytimestation.com/v1/departments \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d name="Sales"
Create Department Response
{ "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 |
Update Department Request
curl https://api.mytimestation.com/v1/departments/dpt_1x95r1zkqf \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d name="Sales" \
-X PUT
Update Department Response
{ "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 |
Delete Department Request
curl https://api.mytimestation.com/v1/departments/dpt_1x95r1zkqf \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-X DELETE
Delete Department Response
{ "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) |
List Shifts Request
curl https://api.mytimestation.com/v1/shifts?employee_id=emp_ekj8x0q7p4&start_date=2023-07-01&end_date=2023-07-15 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:
List Shifts Response
{ "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 |
Single Shift Request
curl https://api.mytimestation.com/v1/shifts/shft_rgnw7mr7q2 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg:
Single Shift Response
{ "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. |
Create Shift Request
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" \
Create Shift Response
{ "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. |
Update Shift Request
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
Update Shift Response
{ "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. |
Close Shift Request
curl https://api.mytimestation.com/v1/shifts/shft_rgnw7mr7q2/close \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-d time_out="2023-07-12T17:00-05:00" \
Close Shift Response
{ "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 |
Delete Shift Request
curl https://api.mytimestation.com/v1/shifts/shft_rgnw7mr7q2 \
-u 4uahz4f7cvj29x63ew65vw3yf9p8rpeg: \
-X DELETE
Delete Shift Response
{ "shift": { "shift_id": "shft_rgnw7mr7q2" }}
