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 prev
ious 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 /schedule
Signup 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,
}
New fields in /schedule#day.assignment.shifts
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.