Our API uses OAuth 2.0 for authentication, specifically the client credentials grant type.
The authentication process consists of requesting an access token with your organization’s
API key and API secret, and using this access token in the Authentication HTTP header
of any subsequent requests.
To generate API key/secret pairs, go to the System Settings page, click “Integrations”, and click “Generate new API credentials”. The credentials will be listed in the table on that page.
If you no longer use the API credentials or you suspect they have been compromised, please delete them, and generate new ones instead, if needed.
Receiving an access token:
curl -v https://api.crewsense.com/oauth/access_token \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_SECRET_KEY" \
-d "grant_type=client_credentials"
If the request is successful and you credentials are correct, you should receive a JSON response like this:
{
"access_token": "DZs3IeaMP5uEAc2I19kJYl8Tbvsmgq9GaPQPaMjN",
"token_type": "bearer",
"expires": 1426274440,
"expires_in": 86400
}
You use access tokens to authorize any requests made towards our API. To request an access token, issue a POST request to https://api.crewsense.com/oauth/access_token
The token_type signifies that you have to use HTTP headers to authorize requests (see the next section).
expires is a UNIX timestamp of the expiration date of the token (after which you have to request a new one).
expires_in shows the expiration length in seconds.
Client access tokens currently expire in one week. If you try to use an expired access token, you might receive a response like:
{
"status": 401,
"error": "unauthorized",
"error_message": "Access token is not valid"
}
In this case, you simply have to request a new access token using the method described above.
curl example
curl -v https://api.crewsense.com/v1/schedule \
-H "Authorization: Bearer DZs3IeaMP5uEAc2I19kJYl8Tbvsmgq9GaPQPaMjN"
To access protected resources in the API, you have to sign the HTTP requests with an Authorization header, using the access_token acquired in the previous step.
Authorization: Bearer DZs3IeaMP5uEAc2I19kJYl8Tbvsmgq9GaPQPaMjN
We use a simplified version of the ISO 8601 standard. Dates are represented in the YYYY-MM-DD format. Most dates with timestamps follow the YYYY-MM-DD hh:mm:ss format (e.g. “2015-03-15 19:33:59”), where the timestamp is “timezoneless”, it is implied to be in your organization’s timezone (or the timezone is irrelevant).
For a few timestamp type data fields, we use the (still ISO 8601 standard) YYYY-MM-DDThh:mm:ss+00:00 format (example: “2015-03-21T19:45:33-06:00”). This is used for fields like contact time, response time, creation date etc., where the timezone may be important (due to daylight savings time for example).
{
"items": [ array of items on the current page of the response ],
"metadata": {
"links": {
"prev": "https://api.crewsense.com/v1/[resource]?limit=50&after=123456",
"next": "https://api.crewsense.com/v1/[resource]?limit=50&after=123556",
}
}
}
Some endpoints might return a large dataset based on the request parameters used. On these endpoints, we split the results into pages to allow for optimal response times and to prevent timeouts. Paginated resources will generally look like the example to the right.
The metadata object will generally include other metadata too, and you get the URL’s for the previous and next pages to request. If prev is null, you are on the first result page, and if next is null, you are on the last page. If both links are null, the result set fit on one page.
Parameters for the prev and next links differ based on the type of resource requested. If request parameters determine a date period to be returned, it will have a start and end parameter for the originally requested period, and an after date parameter that determines the start of the current page. In the response for these endpoints, the metadata object will also contain start, end, page_start and page_end dates, which are the original requested date period, and the returned date period on the current page, respectively. For an example, see GET /time_offs.
GET /day_labels: query day header colors and labels by date range.BREAKING CHANGE Added pagination to the GET /time_offs endpoint, to allow large date periods to be queried efficiently.
GET /time_offs now includes length and real_length (length without break) in the response. Long time off entries are split up into their segments according to the underlying rotation of the user.GET /users/{user_id}/qualifiers and the following few endpoints.accrual_start_date, accrual_profile and accrual_track in GET /users, GET /users/{id} and PATCH /users/{id}Batch processing finaliziations now available!
See POST /finaliziation and DELETE /finaliziation for details.
DELETE /time_offs/{id} endpointGET /scheduleSignup Board now available via API! Create new signup events, list signed up users, add users to the event and more.
10/31/2018{
"length": 24,
"break_start": "2018-10-31 12:00:00",
"break_end": "2018-10-31 12:45:00",
"break_length": 0.75,
}
The following fields have been added to the GET /schedule endpoint, under shifts:
length - The full length of the shift in hours, including break periods.break_start - Start of the break period, if any. null otherwise.break_end - End of the break period, if any. null otherwise.break_length - Length of the break period, if any, in hours.