Fareclock API Documentation

Base URL: https://api.fareclock.com

Table of Contents

• Getting Started
• Concepts
• Endpoints
  • Clock Logs
  • Cost Codes
  • Delete History
  • Departments
  • Devices
  • Duration Entries
  • Employees
  • Job Phases
  • Jobs
  • Organization Units
  • Pay Classes
  • Punches
  • Shift Cards
  • Time Cards
  • Time Off Entries
  • Time Off Codes

---

Getting Started

API Endpoint

https://api.fareclock.com

Authentication

All requests require an API key header:

Authorization: Token YOUR_API_KEY

You can create API keys in Fareclock under Settings → Integrations.

Response Format

JSON is the default response format. You can explicitly request JSON or XML:

Accept: application/json
Accept: application/xml

---

Concepts

Authentication

Fareclock API requests are authenticated with an API key sent in the Authorization header as Token YOUR_API_KEY. Every request must include a valid key, and you can create separate keys with scoped permissions for different integrations.

The Fareclock API uses HTTP access authentication to authenticate each request. Multiple API keys can be created per account to support application isolation. The API keys are set up and managed in the Fareclock Admin Console application.

Authorization: Token MY_API_KEY

To create an API key, sign in to https://www.fareclock.com/login. Then in the top menu bar, go to Settings → Integrations. On the screen below the menu bar, you can add an API key, or edit any existing ones. You can also set specific permissions for an API key.

FAQ

• Where do I put the Fareclock API key? Send it in the Authorization header using the Token scheme.
• Can I create more than one API key? Yes. Multiple API keys per account are supported, which helps separate applications and limit permissions by integration.
• What response should I expect if authentication fails? Failed authentication typically returns HTTP 401 Unauthorized, while valid keys without permission may receive HTTP 403 Forbidden.

Versioning

The current version of the API is 0.2. If unspecified, the default version of the API will always be the latest version.

The version may be specified in the HTTP header:

X-Api-Version: 0.2

If we make changes to the API in the future which are incompatible with the current version, then we will fork a new additional version.

Content Format

The API currently supports JSON and XML formats. Format defaults to JSON, but can be specified in one of three ways, in the following priority order:

1. File-type media extension indicator
2. URL query string
3. HTTP Accept header

Examples:

/punches.json
/punches.xml
?format=json
?format=xml
Accept: application/json
Accept: application/xml

Request Parameters

Filter parameters in GET requests are sent using query string parameters.

Date parameters must be in ISO 8601 datetime format. If just the date part is specified (e.g. 2019-12-31), then if the parameter is for the start of a query range, the beginning of the day will be used (00:00); and if the parameter is for the end of a query range, then end of the day will be used (23:59:59). If time is specified (e.g. 2019-12-31T23:59:00Z), then that exact time will be used. If timezone is not specified, the organization unit timezone will be used, or otherwise the organization timezone.

Some parameters support multiple values. To query for multiple values for a specific field:

field1[]=value1&field1[]=value2&field2=value2&...

Object data in POST/PUT requests are sent in the request body in JSON or XML format.

HTTP Responses

HTTP response status codes reflect the outcome of the request:

Code	Meaning
200	OK — Success
400	Bad Request — Likely invalid format or parameters
401	Unauthorized — Authentication failed
403	Forbidden — Permission refused
404	Not Found — Invalid URL
429	Too Many Requests — Throttle threshold exceeded
500	Internal Server Error

Additional information may be included in the response body, such as resource data and error descriptions.

API Errors

Errors may occur within API semantics. These errors are returned in the HTTP response using the selected content format.

JSON error example:

{"detail": "Invalid token"}

XML error example:

<root><detail>Invalid token</detail></root>

Throttling

Fareclock enforces per-account rate limits of 50 requests per minute and 1,000 requests per hour. When you exceed either threshold, the API returns HTTP 429 Too Many Requests, and the safest client behavior is to stop sending more requests until the limit window resets.

The API currently limits the rate of requests per account:

• Burst rate: 50 / minute
• Sustained rate: 1,000 / hour

Once you reach one of these thresholds, you will receive an HTTP 429 response. You should not continue to query the API when you exceed this threshold, as it may delay the end of the limit period.

FAQ

• What happens when I exceed the API rate limit? The API returns HTTP 429 Too Many Requests after you cross the burst or sustained limit.
• Should my client keep retrying after a 429? No. Stop sending additional requests until the limit window passes.
• Are async poll requests counted toward throttling? Yes. Async polling still counts toward throttle limits.

Paging

Fareclock paging lets clients retrieve large list results in smaller chunks by sending cursor, direction, and limit query parameters. When a response includes a cursor for the next page, reuse the same filters on every subsequent request and treat the cursor as an opaque value.

Some API List methods support paging in order to support larger data sets.

Parameter	Description
cursor	Inclusive value where to begin paged results, i.e. after where last page left off. Defaults to beginning or end of list, depending on direction.
direction	1 to list values after cursor, 0 to list values before cursor. Defaults to 1.
limit	Number of results per page. Usually defaults to 25, maximum 200.

If the result set was paged, the response will contain a cursor value indicating where to begin the next page. The cursor value should be treated as an opaque string and not modified. Each subsequent page request should contain the exact identical filter query parameters as the first page.

FAQ

• Which query parameters control paging? cursor, direction, and limit.
• Can I change filters between paged requests? No. Keep the same filters on every page request.
• Should I parse or modify the cursor value? No. Treat it as an opaque string and return it exactly as received.

Async Invocation

Use asynchronous invocation when a supported list request may take too long to complete synchronously. Start the job with POST {base_url}/async, store the returned reportKey, and poll GET {base_url}/async/{REPORT_KEY}/poll no more than once every 10 seconds until the server returns HTTP 200.

Standard synchronous invocation of List methods may time out for larger data sets. Those collections which support asynchronous invocation are noted in each endpoint below.

To invoke the asynchronous List method, add the following URL suffix after the base method:

POST {base_url}/async?{query_parameters}

This POST call should return HTTP status 202 with a response body:

{ "success": true, "reportKey": "{REPORT_KEY}" }

Using the REPORT_KEY, poll for the results at:

GET {base_url}/async/{REPORT_KEY}/poll

• If poll returns HTTP 202, the server is still processing. Try again later.
• If poll returns HTTP 200, the report is complete and the response body contains the result.

You should not poll more frequently than once every 10 seconds. Each poll call counts toward throttle.

FAQ

• When should I use async instead of a normal GET list request? Use it when a supported collection may return enough data to time out in a normal synchronous request.
• What does HTTP 202 mean during async polling? The report is still being generated and is not ready yet.
• How often should I poll for async results? No more than once every 10 seconds.

Field Selection

Some of the newer API methods support the ability to select which fields should be included. This can save memory, bandwidth, and latency. Fields can be selected via the fields query string parameter:

?fields[]=firstName&fields[]=lastName&fields[]=duration

Supplemental Data

Some of the newer API methods include a separate supplementalData section in the response containing related data. For example, instead of repeating employeeFirstName and employeeLastName on every punch, only the employee ID is included in each result, and the supplementalData section contains a dictionary of employee data keyed by ID.

By default, all supplemental data is included. To exclude it entirely:

?supplementalData=no

To specify which supplemental data kinds to include:

?supplementalDataFields[]=employee&supplementalDataFields[]=department

Collection Capabilities

Collection	Async Invocation	Paging	Field Selection	Supplemental Data	Notes
Clock Logs	YES	NO	NO	YES	Paging is not supported.
Cost Codes	NO	YES	NO	YES	Paging results are ordered by name.
Delete History	NO	YES	NO	NO	Paging is ordered by deletion timestamp.
Departments	NO	NO	NO	NO	Paging is not supported.
Devices	NO	YES	NO	YES	Paging results are ordered by name.
Employees	NO	YES	NO	NO	Paging results are ordered by sort name.
Job Phases	NO	YES	NO	YES	Paging results are ordered by name.
Jobs	NO	YES	NO	YES	Paging results are ordered by job name.
Organization Units	NO	NO	NO	NO	Paging is not supported.
Pay Classes	NO	NO	NO	NO	Paging is not supported.
Punches	YES	YES	NO	YES	Paging condition: orderBy=modified and direction=1 (ascending).
Shift Cards	YES	NO	NO	YES	Paging is not supported.
Time Cards	YES	NO	NO	YES	Paging is not supported.
Time Off Codes	NO	NO	NO	NO	Paging is not supported.
Duration Entries	NO	YES	YES	YES	Paging condition: orderBy=modified and direction=1 (ascending).
Time Off Entries	YES	NO	NO	YES	Supports create, update, and delete operations on time off entries.

---

Endpoints

Clock Logs

Features supported

• Support asynchronous invocation: YES
• Supports paging: NO
• Field selection: NO
• Supplemental data: YES

GET /clocklogs — List all Clock Logs

Query Parameters

Parameter	Type	Required	Description
from	date	Yes	Start of date range for clock log timestamp.
to	date	Yes	End of date range.
employee	integer	No	Employee ID.
clockOrgUnit	integer	No	Organization unit ID of clock/device.
workOrgUnit	integer	No	Organization unit ID of employee work location.
department	integer	No	Department ID.
status	string	No	Comma-separated status values (e.g. approved, offline).
clock	integer	No	Clock/device ID.
labels	string	No	Labels filter string (e.g. user:123 or work:123).
job	integer	No	Job ID.
userCustomFields	string	No	Custom fields query string.

Response

{
  "results": [
    {
      "id": 800,
      "employee": 300,
      "employeeFirstName": "John",
      "employeeLastName": "Doe",
      "clock": 600,
      "clockName": "Clock #1",
      "clockOrgUnit": 100,
      "clockOrgUnitName": "Organization Unit #1",
      "timezone": "America/New_York",
      "orgUnit": 100,
      "orgUnitName": "Organization Unit #1",
      "department": 200,
      "departmentName": "Department #1",
      "dt": "2020-06-02T09:00:00Z",
      "offline": false,
      "status": "approved",
      "created": "2020-06-02T09:00:00.123Z",
      "modified": "2020-06-02T09:00:00.123Z"
    }
  ]
}

GET /clocklogs/{id} — Retrieve a Clock Log

Response

Matches the response schema of GET /clocklogs.

---

Cost Codes

Features supported

• Support asynchronous invocation: NO
• Supports paging: YES
• Field selection: NO
• Supplemental data: YES

GET /costcodes — List all Cost Codes

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the cost code.
search	string	No	Case-insensitive full text search of name.
active	string	No	active or inactive.

Response

{
  "results": [
    {
      "id": 10,
      "name": "Regular Construction",
      "active": true,
      "payrollId": "CC-REG",
      "allowLabels": ["device:all", "user:all", "work:all"],
      "labels": [],
      "created": "2020-06-02T09:00:00.000Z",
      "modified": "2020-06-02T09:00:00.000Z"
    }
  ]
}

POST /costcodes — Create a Cost Code

Request Body

{
  "name": "Regular Construction",
  "active": true,
  "payrollId": "CC-REG",
  "allowLabels": ["device:all", "user:all", "work:all"]
}

Response

Matches the schema of GET /costcodes.

GET /costcodes/{id} — Retrieve a Cost Code

PUT /costcodes/{id} — Update a Cost Code

---

Delete History

Features supported

• Support asynchronous invocation: NO
• Supports paging: YES, ordered by deletion timestamp
• Field selection: NO
• Supplemental data: NO

GET /delete-history — List all Delete History Items

Query Parameters

Parameter	Type	Required	Description
from	date	No	Start of date range for deletion timestamp.
to	date	No	End of date range for deletion timestamp.
kind	string	No	Object kind. Valid values: durationEntry, employee, punch, punchCode.
deletedId	integer	No	ID of the deleted object.

Response

{
  "results": [
    {
      "id": 400,
      "timestamp": "2020-05-07T14:30:00Z",
      "kind": "employee",
      "deletedId": 500,
      "user": 100
    }
  ]
}

---

Departments

Features supported

• Support asynchronous invocation: NO
• Supports paging: NO
• Field selection: NO
• Supplemental data: NO

GET /departments — List all Departments

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the department.

Response

{
  "results": [
    {
      "id": 200,
      "name": "Department #1",
      "active": true,
      "payrollId": "dept-1",
      "created": "2020-06-02T09:00:00.000Z",
      "modified": "2020-06-02T09:00:00.000Z"
    }
  ]
}

POST /departments — Create a Department

Request Body

{
  "name": "Department #1",
  "active": true,
  "payrollId": "dept-1"
}

Response

Matches the schema of GET /departments.

GET /departments/{id} — Retrieve a Department

PUT /departments/{id} — Update a Department

---

Devices

Features supported

• Support asynchronous invocation: NO
• Supports paging: YES
• Field selection: NO
• Supplemental data: YES

GET /devices — List all Devices

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the device.
search	string	No	Case-insensitive full text search of device name.
orgUnit	integer	No	Organization unit ID of the device.
active	string	No	active or inactive.

Response

{
  "results": [
    {
      "id": 600,
      "name": "Clock #1",
      "active": true,
      "orgUnit": 100,
      "orgUnitName": "Organization Unit #1",
      "clockSessionValid": true,
      "settingsPinAllowLabels": null,
      "geoRules": [],
      "clockSessionIpAddress": "192.168.1.50",
      "clockSessionUserAgent": "Fareclock Timeclock App",
      "clockSessionDeviceModel": "iPad Air",
      "clockSessionDeviceUuid": "uuid-123456",
      "clockSessionAppVersion": "3.5.7",
      "clockSessionSubmitLogs": false,
      "created": "2020-06-02T09:00:00.000Z",
      "modified": "2020-06-02T09:00:00.000Z"
    }
  ]
}

POST /devices — Create a Device

Request Body

{
  "name": "Clock #1",
  "active": true,
  "orgUnit": 100
}

Response

Matches the schema of GET /devices.

GET /devices/{id} — Retrieve a Device

PUT /devices/{id} — Update a Device

POST /devices/{id}/reset — Reset a Device Session

POST /devices/{id}/request-logs — Request Logs from Device

---

Duration Entries

Features supported

• Support asynchronous invocation: NO
• Supports paging: YES, ordered by modified timestamp
• Field selection: YES
• Supplemental data: YES

GET /duration-entries — List all Duration Entries

Query Parameters

Parameter	Type	Required	Description
from	date	Yes	Start of date range (or modified range if orderBy=modified).
to	date	Yes	End of date range.
employee	integer	No	Employee ID.
orgUnit	integer	No	Organization unit ID of employee.
department	integer	No	Department ID.
payClass	integer	No	Pay class ID.
labels	integer	No	User label ID.
userCustomFields	string	No	Custom fields query string.
orderBy	string	No	date (default) or modified.

Response

{
  "results": [
    {
      "id": 4538783999459328,
      "type": "PAID_TIME_OFF",
      "date": "2020-06-02",
      "duration": 480.0,
      "employee": 6122080743456768,
      "orgUnit": 6403555720167424,
      "department": 4996180836614144,
      "payClass": 5277655813324800,
      "labels": ["user:5559130790035456"],
      "lastEditedBy": null,
      "timeOffCode": 6685030696878080,
      "timeOffRequest": null,
      "created": "2020-06-02T23:11:08.690835Z",
      "modified": "2020-06-02T23:11:08.696838Z"
    }
  ]
}

GET /duration-entries/{id} — Retrieve a Duration Entry

Response

Matches the schema of GET /duration-entries.

---

Employees

Features supported

• Support asynchronous invocation: NO
• Supports paging: YES
• Field selection: NO
• Supplemental data: NO

GET /employees — List all Employees

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the employee.
employee	string	No	Case-insensitive full text search of employee name.
orgUnit	integer	No	Organization unit ID.
department	integer	No	Department ID.
payClass	integer	No	Pay class ID.
labels	integer	No	User label ID.
active	string	No	active or inactive.
credentialPolicy	integer	No	Credential policy ID.
credentialType	integer	No	Credential type ID.
credentialValid	string	No	valid, invalid, or all.
hasFaceModel	string	No	yes or no.
requireJobAccess	string	No	yes or no.
orderBy	string	No	name (default) or modified.
from	date	No	Start of date range for modification timestamp.
to	date	No	End of date range for modification timestamp.

Response

{
  "results": [
    {
      "id": 300,
      "active": true,
      "roles": ["worker"],
      "firstName": "John",
      "lastName": "Doe",
      "middleName": null,
      "displayName": "John Doe",
      "sortName": "doe, john",
      "accepted": false,
      "permissions": [],
      "notifications": ["clock_alerts"],
      "lastAccess": null,
      "banned": false,
      "workerAllowLabels": [],
      "adminAllowLabels": [],
      "requireJobAccess": false,
      "orgUnit": 100,
      "orgUnitName": "Organization Unit #1",
      "orgUnitPayrollId": null,
      "timezone": "America/New_York",
      "department": 200,
      "departmentName": "Department #1",
      "departmentPayrollId": null,
      "teamSchedule": null,
      "teamScheduleName": null,
      "payClass": 500,
      "payClassName": "Regular Hourly",
      "timeOffPolicy": null,
      "disciplinePolicy": null,
      "pointBalance": null,
      "nextShiftReminder": null,
      "pin": "123456",
      "qrCode": null,
      "nfcTagId": null,
      "payrollId": null,
      "neverHadFace": false,
      "lastPunch": "2014-04-03T17:28:24.326Z",
      "hasDocuments": false,
      "hasCredentials": false,
      "credentialPolicy": null,
      "credentialPolicyName": null,
      "invalidCredentialing": false,
      "inducted": false,
      "contactSuppressions": null,
      "announcement": null,
      "announcementOverride": false,
      "personalDeviceMode": null,
      "personalAuthPunchOnly": false,
      "personalAdminPerms": [],
      "reinstallPerm": null,
      "geoRules": [],
      "mobilePhone": null,
      "installCode": null,
      "fixJob": null,
      "fixJobLabel": null,
      "fixJobPhase": null,
      "fixCostCode": null,
      "fixCostingIsPartial": false,
      "bgGeoConnectionState": null,
      "address": null,
      "addressGeoCode": null,
      "phones": [],
      "email": null,
      "gender": null,
      "birthDate": null,
      "nationalId": null,
      "nationalIdKey": null,
      "driversLic": null,
      "driversLicExpDate": null,
      "passportNo": null,
      "passportExpDate": null,
      "nationality": null,
      "hireDate": null,
      "hireBy": null,
      "jobTitle": null,
      "termDate": null,
      "hirePeriods": [],
      "payRates": [],
      "bankInfo": {},
      "notes": null,
      "emgContact": null,
      "emgRelation": null,
      "emgPhones": [],
      "emgEmail": null,
      "emgAddress": null,
      "distributor": null,
      "customFieldValues": [],
      "created": "2013-12-06T20:38:21.347Z",
      "modified": "2014-04-03T17:28:24.326Z"
    }
  ]
}

POST /employees — Create an Employee

Request Body

{
  "active": true,
  "firstName": "John",
  "lastName": "Doe",
  "orgUnit": 100,
  "department": 200,
  "pin": "123456",
  "phones": []
}

Response

{
  "results": [
    {
      "id": 300,
      "active": true,
      "firstName": "John",
      "lastName": "Doe",
      "orgUnit": 100,
      "orgUnitName": "Organization Unit #1",
      "department": 200,
      "departmentName": "Department #1",
      "timezone": "America/New_York",
      "payrollId": null,
      "created": "2013-12-06T20:38:21.347Z",
      "modified": "2013-12-06T20:38:21.347Z"
    }
  ]
}

GET /employees/{id} — Retrieve an Employee

PUT /employees/{id} — Update an Employee

DELETE /employees/{id} — Delete an Employee

---

Job Phases

Features supported

• Support asynchronous invocation: NO
• Supports paging: YES
• Field selection: NO
• Supplemental data: YES

GET /jobphases — List all Job Phases

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the job phase.
search	string	No	Case-insensitive full text search of name.
active	string	No	active or inactive.

Response

{
  "results": [
    {
      "id": 20,
      "name": "Phase 1 - Planning",
      "active": true,
      "payrollId": "JP-PH1",
      "allowLabels": ["device:all", "user:all", "work:all"],
      "labels": [],
      "created": "2020-06-02T09:00:00.000Z",
      "modified": "2020-06-02T09:00:00.000Z"
    }
  ]
}

POST /jobphases — Create a Job Phase

Request Body

{
  "name": "Phase 1 - Planning",
  "active": true,
  "payrollId": "JP-PH1",
  "allowLabels": ["device:all", "user:all", "work:all"]
}

Response

Matches the schema of GET /jobphases.

GET /jobphases/{id} — Retrieve a Job Phase

PUT /jobphases/{id} — Update a Job Phase

---

Jobs

Features supported

• Support asynchronous invocation: NO
• Supports paging: YES, ordered by job name
• Field selection: NO
• Supplemental data: YES

GET /jobs — List all Jobs

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the job.
active	string	No	active or inactive.
search	string	No	Case-insensitive full text search of job name.
labels	integer	No	Work label ID.
orgUser	integer	No	Employee ID.

Response

{
  "results": [
    {
      "id": 1,
      "name": "Job #1",
      "active": true,
      "description": "Building construction work",
      "payrollId": "job-1-payroll-id",
      "orgUsers": [],
      "notifyOrgUsers": [],
      "allowLabels": ["device:all", "user:all"],
      "labels": [],
      "jobPhaseMode": null,
      "costCodeMode": null,
      "created": "2014-01-01T18:53:46.016Z",
      "modified": "2014-01-03T12:44:17.935Z"
    }
  ]
}

POST /jobs — Create a Job

Request Body

{
  "name": "Job #1",
  "active": true,
  "description": "Building construction work",
  "payrollId": "job-1-payroll-id",
  "allowLabels": ["device:all", "user:all"]
}

Response

Matches the schema of GET /jobs.

GET /jobs/{id} — Retrieve a Job

PUT /jobs/{id} — Update a Job

---

Organization Units

Features supported

• Support asynchronous invocation: NO
• Supports paging: NO
• Field selection: NO
• Supplemental data: NO

GET /orgunits — List all Organization Units

Query Parameters

Parameter	Type	Required	Description
orgUnit	integer	No	Numeric ID of the organization unit.

Response

{
  "results": [
    {
      "id": 100,
      "name": "Organization Unit #1",
      "active": true,
      "payrollId": "org-unit-1",
      "timezone": "America/New_York",
      "created": "2020-06-02T09:00:00.000Z",
      "modified": "2020-06-02T09:00:00.000Z"
    }
  ]
}

POST /orgunits — Create an Organization Unit

Request Body

{
  "name": "Organization Unit #1",
  "active": true,
  "payrollId": "org-unit-1",
  "timezone": "America/New_York"
}

Response

Matches the schema of GET /orgunits.

GET /orgunits/{id} — Retrieve an Organization Unit

PUT /orgunits/{id} — Update an Organization Unit

GET /orgunits/{id}/allowed-employees — List Allowed Employees

---

Pay Classes

Features supported

• Support asynchronous invocation: NO
• Supports paging: NO
• Field selection: NO
• Supplemental data: NO

GET /payclasses — List all Pay Classes

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the pay class.

Response

{
  "results": [
    {
      "id": 500,
      "active": true,
      "name": "Regular Hourly",
      "payMode": "hourly",
      "enableNetPay": false,
      "payPeriod": "week",
      "payPeriodStartsOn": 1,
      "payDateDaysAfter": 1,
      "regularPayCode": 10,
      "daily1Threshold": "08:00:00",
      "daily1PayCode": 11,
      "weekly1Threshold": "40:00:00",
      "weekly1PayCode": 11,
      "created": "2020-06-02T09:00:00.000Z",
      "modified": "2020-06-02T09:00:00.000Z"
    }
  ]
}

POST /payclasses — Create a Pay Class

Request Body

{
  "name": "Regular Hourly",
  "active": true,
  "payMode": "hourly",
  "regularPayCode": 10,
  "daily1Threshold": "08:00:00",
  "daily1PayCode": 11,
  "weekly1Threshold": "40:00:00",
  "weekly1PayCode": 11
}

Response

Matches the schema of GET /payclasses.

GET /payclasses/{id} — Retrieve a Pay Class

PUT /payclasses/{id} — Update a Pay Class

---

Punches

Features supported

• Support asynchronous invocation: YES
• Supports paging: YES, ordered by modified timestamp
• Field selection: NO
• Supplemental data: YES

GET /punches — List all Punches

Query Parameters

Parameter	Type	Required	Description
from	date	Yes	Start of date range. Punch pairs are dated by the IN punch (or modified timestamp if orderBy=modified).
to	date	Yes	End of date range.
orderBy	string	No	punch (default) or modified.
employee	integer	No	Employee ID.
job	integer	No	Job ID.
orgUnit	integer	No	Organization unit ID of employee.
clockOrgUnit	integer	No	Organization unit ID of clock.
workOrgUnit	integer	No	Organization unit ID of work location.
department	integer	No	Department ID.
device	integer	No	Clock/device ID.
status	string	No	Status tag string (e.g. approved, flagged).
labels	integer	No	User or work label ID.
userCustomFields	string	No	Custom fields query string.
entryState	integer	No	Entry state ID.
payClass	integer	No	Pay class ID.

Response

{
  "results": [
    {
      "id": 400,
      "employee": 300,
      "employeeFirstName": "John",
      "employeeLastName": "Doe",
      "employeePayrollId": "employee-payroll-id",
      "orgUnit": 100,
      "orgUnitName": "Org Unit #1",
      "timezone": "America/New_York",
      "inDt": "2014-03-07T14:30:00Z",
      "inClock": 600,
      "inClockName": "Clock #1",
      "inOrgUnit": 101,
      "inOrgUnitName": "Org Unit #1",
      "inExceptions": ["added"],
      "outDt": "2014-03-07T15:30:00Z",
      "outClock": 600,
      "outClockName": "Clock #1",
      "outExceptions": ["edited"],
      "status": "approved",
      "overrideBy": "Mike Manager",
      "created": "2014-03-10T01:45:19.369Z",
      "modified": "2014-04-03T16:54:05.246Z"
    }
  ]
}

POST /punches — Create a Punch

Request Body

{
  "employee": 300,
  "inDt": "2014-03-07T14:30:00Z",
  "inOrgUnit": 101,
  "outDt": "2014-03-07T15:30:00Z",
  "outOrgUnit": 101
}

Response

Matches the schema of GET /punches.

GET /punches/{id} — Retrieve a Punch

PUT /punches/{id} — Update a Punch

PUT requests are applied as partial updates. Omitted fields are left unchanged.

Request Body

{
  "outDt": "2014-03-07T16:00:00Z",
  "outOrgUnit": 101,
  "notes": "adjusted clock-out after manager review"
}

Response

Matches the schema of GET /punches.

DELETE /punches/{id} — Delete a Punch

Returns 204 No Content when deletion succeeds.

---

Shift Cards

Features supported

• Support asynchronous invocation: YES
• Supports paging: NO
• Field selection: NO
• Supplemental data: YES

GET /shiftcards — List all Shift Cards

Query Parameters

Parameter	Type	Required	Description
from	date	Yes	Start of date range.
to	date	Yes	End of date range.
employee	integer	No	Employee ID.
orgUnit	integer	No	Organization unit ID of employee.
department	integer	No	Department ID.
payClass	integer	No	Pay class ID.
labels	integer	No	User or work label ID.
tag	string	No	Tag string filter.
userCustomFields	string	No	Custom fields query string.

Response

{
  "results": [
    {
      "id": 1000,
      "employee": 300,
      "orgUnit": 100,
      "department": 200,
      "employeePayClass": 500,
      "shiftClass": 1100,
      "timezone": "America/New_York",
      "date": "2020-06-02",
      "shiftDate": "2020-06-02",
      "start": "2020-06-02T09:00:00Z",
      "end": "2020-06-02T17:00:00Z",
      "punches": [
        {
          "id": 400,
          "in": "2020-06-02T09:00:00Z",
          "out": "2020-06-02T17:00:00Z",
          "status": "approved",
          "processedTotal": 28800.0,
          "rawTotal": 28800.0
        }
      ],
      "isTardy": false,
      "hasException": false,
      "hasFlagged": false,
      "created": "2020-06-02T09:00:00Z",
      "modified": "2020-06-02T09:00:00Z"
    }
  ]
}

---

Time Cards

Features supported

• Support asynchronous invocation: YES
• Supports paging: NO
• Field selection: NO
• Supplemental data: YES

GET /timecards — List all Time Cards

Query Parameters

Parameter	Type	Required	Description
from	date	Yes	Start of date range for shift cards.
to	date	Yes	End of date range for shift cards.
employee	integer	No	Employee ID.
orgUnit	integer	No	Organization unit ID of employee.
department	integer	No	Department ID.
payClass	integer	No	Pay class ID.
labels	integer	No	User or work label ID.
tag	string	No	Tag string filter.
userCustomFields	string	No	Custom fields query string.

Response

{
  "results": [
    {
      "id": 1000,
      "employee": 300,
      "orgUnit": 100,
      "department": 200,
      "employeePayClass": 500,
      "shiftClass": 1100,
      "timezone": "America/New_York",
      "date": "2020-06-02",
      "shiftDate": "2020-06-02",
      "start": "2020-06-02T09:00:00Z",
      "end": "2020-06-02T17:00:00Z",
      "punches": [
        {
          "id": 400,
          "inDt": "2020-06-02T09:00:00Z",
          "outDt": "2020-06-02T17:00:00Z",
          "status": "approved",
          "processedTotal": 28800.0,
          "rawTotal": 28800.0
        }
      ],
      "created": "2020-06-02T09:00:00Z",
      "modified": "2020-06-02T09:00:00Z"
    }
  ]
}

Time Off Entries

Features supported

• Support asynchronous invocation: YES
• Supports paging: NO
• Field selection: NO
• Supplemental data: YES

GET /timeoffentries — List all Time Off Entries

Query Parameters

Parameter	Type	Required	Description
from	date	Yes	Start of date range for time off entry date.
to	date	Yes	End of date range.
orgUnit	integer	No	Organization unit ID of employee.
department	integer	No	Department ID.
payClass	integer	No	Pay class ID.
labels	integer	No	User label ID.
worker	integer	No	Employee ID.
timeOffCode	integer	No	Time Off Code ID.
userCustomFields	string	No	Custom fields query string.

Response

{
  "results": [
    {
      "id": 4538783999459328,
      "type": "PAID_TIME_OFF",
      "date": "2020-06-02",
      "duration": 480.0,
      "employee": 6122080743456768,
      "orgUnit": 6403555720167424,
      "department": 4996180836614144,
      "payClass": 5277655813324800,
      "labels": ["user:5559130790035456"],
      "lastEditedBy": "admin@example.com",
      "timeOffCode": 6685030696878080,
      "timeOffRequest": null,
      "created": "2020-06-02T23:11:08.690835Z",
      "modified": "2020-06-02T23:11:08.696838Z"
    }
  ]
}

POST /timeoffentries — Create a Time Off Entry

Request Body

{
  "employee": 6122080743456768,
  "date": "2020-06-02",
  "timeOffCode": 6685030696878080,
  "duration": 480,
  "notes": "api create"
}

GET /timeoffentries/{id} — Retrieve a Time Off Entry

PUT /timeoffentries/{id} — Update a Time Off Entry

DELETE /timeoffentries/{id} — Delete a Time Off Entry

---

Time Off Codes

Features supported

• Support asynchronous invocation: NO
• Supports paging: NO
• Field selection: NO
• Supplemental data: NO

GET /timeoffcodes — List all Time Off Codes

Query Parameters

Parameter	Type	Required	Description
id	integer	No	Numeric ID of the time off code.

Response

{
  "results": [
    {
      "id": 6685030696878080,
      "name": "Vacation",
      "active": true,
      "payrollId": "VAC",
      "sortOrder": 1,
      "isPaid": true,
      "allowWorkerRequest": true,
      "created": "2020-06-02T09:00:00.000Z",
      "modified": "2020-06-02T09:00:00.000Z"
    }
  ]
}

POST /timeoffcodes — Create a Time Off Code

Request Body

{
  "name": "Vacation",
  "active": true,
  "payrollId": "VAC",
  "sortOrder": 1,
  "isPaid": true,
  "allowWorkerRequest": true
}

Response

Matches the schema of GET /timeoffcodes.

GET /timeoffcodes/{id} — Retrieve a Time Off Code

PUT /timeoffcodes/{id} — Update a Time Off Code