NAV
cURL

Introduction

Welcome to the CrewSense API

Find out how to send requests to our API, and what you can do with it using this developer resource.

The CrewSense API exposes very useful endpoints from within the CrewSense platform. You can do things like query the Schedule, manage Roster Data, Add Time Off’s, Manage Trades, View System Log entries, CallBack History, and much more.

All of our examples are in cURL, however any scripting language that supports RESTful calls can be utilized.

Authentication

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.

Getting your API credentials

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

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.

Authorizing requests

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

Conventions

Date and time

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).

Pagination

{
    "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.

Changelog

12/18/2018

BREAKING CHANGE Added pagination to the GET /time_offs endpoint, to allow large date periods to be queried efficiently.

12/12/2018

12/11/2018

12/04/2018

Batch processing finaliziations now available!
See POST /finaliziation and DELETE /finaliziation for details.

11/10/2018

11/02/2018

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:

Schedule

The schedule end point consists of shifts, time offs, callbacks, trades, notes, activities and misc. hours. They are wrapped by a top-level object containing metadata about the requested schedule (start date, end date, links for the next and previous period).

In the following sections, we try to introduce all the important data in the schedule resource.

GET /schedule

Example request

curl -v https://api.crewsense.com/v1/schedule -G \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d "start=2015-03-15 08:00:00" \
     -d "end=2015-03-22 08:00:00"

An example of returned /schedule data GET request looks like this:

{
   "start": "2015-03-15 08:00:00",
   "end": "2015-03-22 08:00:00",

   "days": [
      {
         "date": "2015-03-15",
         "assignments": [
            {
               "shifts": [
                  ...shift data displayed here...
               ],
            }
         ],
         "time_off": [
            {
               ...time off data displayed here...
            }
         ],
         "callbacks": [
            {
               ...callback data displayed here...
            }
         ],
         "trades": [
            {
               ...trade data displayed here...
            }
         ],
         "misc": [
            {
               ... misc hours data displayed here...
            }
         ]
      }
   ],

   "prev": {
      "href": "https://api.crewsense.com/v1/schedule?start=2015-03-08%2008:00:00&end=2015-03-15%2008:00:00"
   },
   "next": {
      "href": "https://api.crewsense.com/v1/schedule?start=2015-03-22%2008:00:00&end=2015-03-22%2008:00:00"
   }
}

GET /schedule

This endpoint has two required parameters:

Query Parameters

Field Description Format
start The date you need the data from datetime
end The date you need the data to datetime

days

This array contains all days occurring between the start and end date requested. Each object in the array contains the date key, and arrays of objects occurring that day. For the following sections, we refer to one object in this array as a day.

day.assignments

{
    "id": 1234,
    "href": "https://api.crewsense.com/v1/assignments/1234",
    "date": "2015-03-15",
    "start": "2015-03-15 08:00:00",
    "end": "2015-03-16 08:00:00",
    "name": "Station 1",
    "qualifiers_needed": [
        {
            "id": 7,
            "name": "Captains",
            "shortcode": "CPT",
            "color": "#d81b60",
            "text_color": "#FFFFFF",
            "minimum_staffing": 1
        },
        {
            "id": 8,
            "name": "Firefighters",
            "shortcode": "FF-01",
            "color": "#e53935",
            "text_color": "#000000",
            "minimum_staffing": 2
        }
    ],
    "minimum_staffing": 3,
    "is_finalized": true,
    "notes": "Assignment notes on date",
    "shifts": [
        ... see next section ...
    ]
}

This array contains the Crew Scheduler assignments of the day.

Parameters

Field Description Type
id Unique identifier of the assignment integer
href Link to full object string (URL)
date The day the assignment starts on date
start Start date of assignment datetime
end End date of assignment datetime
name Title of assignment string
qualifiers_needed Qualifier requirements for the assignment, if any. The minimum_staffing fields hold the number of people needed for the position. array
minimum_staffing Employees needed integer
is_finalized Is the assignment finalized on the date boolean
notes Assignment notes on the date string
shifts Employees working the assignment array

day.assignment.shifts

{
   "id": 456789,
   "href": "https://api.crewsense.com/v1/shifts/456789",
   "start": "2015-03-15 08:00:00",
   "end": "2015-03-16 08:00:00",
   "length": 24,
   "break_start": "2015-03-15 12:00:00",
   "break_end": "2015-03-15 12:30:00",
   "break_length": 0.5,
   "hold_over": 0,
   "recurring": true,
   "user": {
      "id": 848,
      "href": "https://api.crewsense.com/v1/users/848",
      "name": "John Doe"
   },
   "scheduled_by": {
      "id": 138,
      "href": "https://api.crewsense.com/v1/users/138",
      "name": "Joe Boss"
   },
   "work_type": {
      "id": 33,
      "href": "https://api.crewsense.com/v1/work_types/33",
      "name": "Regular Time",
      "work_code": "REG001",
      "color": "#3B4650",
      "text_color": "#FFFFFF",
      "subtypes": [
        {
          "id": 2,
          "label": "Mandatory"
        }
      ]
   },
   "labels": [
      {
         "id": 12,
         "href": "https://api.crewsense.com/v1/labels/12",
         "label": "ENG",
         "color": "#CCCCCC",
         "text_color": "#333333"
      }
   ],
   "qualifiers": [
      {
         "id": 7,
         "href": "https://api.crewsense.com/v1/qualifiers/7",
         "shortcode": "CPT",
         "name": "Captains",
         "color": "#d81b60",
         "text_color": "#FFFFFF"
      }
   ],
   "groups": [
      {
         "id": 2108,
         "label": "A Shift"
      }
   ]
}

This array holds data about the employees scheduled for the assignment on the given day.

Fields

Field Description Type
id Unique identifier of the work shift integer
href Link to full object string (URL)
start Start date of shift datetime
end End date of shift datetime
length The full length of the shift (including breaks) in hours float
break_start Start of the break period, if any datetime
break_end End of the break period, if any datetime
break_length Length of the break period in hours float
recurring Is it a regularly occurring shift? boolean
user Employee working the shift See Users
scheduled_by Admin who assigned the shift See Users
work_type Type of work shift See Work Types
labels Applied Crew Scheduler labels See Labels
qualifiers Applied CrewSense Qualifiers on the shift See Qualifiers
groups User groups set to be indicated in the schedule See Groups

day.time_off

{
   "id": 623492,
   "href": "https://api.crewsense.com/v1/time_off/623492",
   "start": "2015-03-15 08:00:00",
   "end": "2015-03-16 08:00:00",
   "user": {
      "id": 848,
      "href": "https://api.crewsense.com/v1/users/848",
      "name": "John Doe"
   },
   "admin": {
      "id": 138,
      "href": "https://api.crewsense.com/v1/users/138",
      "name": "Joe Boss"
   },
   "time_off_type": {
      "id": 45,
      "href": "https://api.crewsense.com/v1/time_off_types/45",
      "name": "Vacation",
      "work_code": "VAC",
      "color": "#3f5647",
      "text_color": "#FFFFFF",
      "subtypes": [
        {
          "id": 1,
          "label": "Mandatory"
        },
        {
          "id": 3,
          "label": "Comp"
        }
      ]
   }
}

All approved time off for the day is in this array, including long term and recurring leave that has an occurrence fall on this day.

Parameters

Field Description Type
id Unique identifier of the time off integer
href Link to full object string (URL)
start Start date of time off entry datetime
end End date of time off entry datetime
user Employee on time off See Users
admin Admin who approved time off See Users
time_off_type Type of time off See Time off Types

day.callbacks

{
   "id": 64012,
   "href": "https://api.crewsense.com/v1/callbacks/64012",
   "start": "2015-03-15 08:00:00",
   "end": "2015-03-16 08:00:00",
   "minimum_staffing": 1,
   "records": [
      {
         "id": 2165743,
         "user": {
            "id": 848,
            "href": "https://api.crewsense.com/v1/users/848",
            "name": "John Doe"
         },
         "start": "2015-03-15 08:00:00",
         "end": "2015-03-16 08:00:00",
         "work_site": null
      }
   ],
   "title": {
      "id": 112,
      "href": "https://api.crewsense.com/v1/titles/112",
      "name": "Firefighter"
   }
}

In this array you will find all finalized CallBacks for the day. CallBack shifts that were drag & dropped to a work assignment will not be included, as they are found under day.assignment.shifts

Query Parameters

Field Description Type
id Unique identifier of the callback integer
href Link to full object string (URL)
start Start date of the callback shift datetime
end End date of the callback shift datetime
minimum_staffing Number of employees needed in this callback integer
records Accepting employees array; see Callback Users
title Employee type needed time off See section-title

day.trades

{
   "id": 4355,
   "href": "https://api.crewsense.com/v1/trades/4355",
   "start": "2015-03-15 08:00:00",
   "end": "2015-03-16 08:00:00",
   "requesting_user": {
      "id": 848,
      "href": "https://api.crewsense.com/v1/users/848",
      "name": "John Doe"
   },
   "accepting_user": {
      "id": 138,
      "href": "https://api.crewsense.com/v1/users/138",
      "name": "Jack Smith"
   },
   "admin": {
      "id": 98,
      "href": "https://api.crewsense.com/v1/users/98",
      "name": "Steve Boss"
   }
}

Follow the top-level href link to receive all information about the trade.

Contains all accepted and finalized shift trades for the day.

day.misc

{
   "id": 47711,
   "href": "https://api.crewsense.com/v1/misc/47711",
   "date": "2015-03-16",
   "length": 4.5,
   "user": {
      "id": 848,
      "href": "https://api.crewsense.com/v1/users/848",
      "name": "John Doe"
   },
   "work_type": "Training"
}

This array provides data about any miscellaneous hours added for the day.

day.notes, day.activities

This contains the Crew Scheduler notes for the day formatted in HTML format

Assignments

Allows you to retrieve, modify and create new CrewScheduler Assignments

GET /assignments

Example response

[
  {
    "id": 123,
    "position": 3,
    "name": "Station 1",
    "date": "2014-01-22",
    "start": "2014-01-22 08:00:00",
    "end": "2014-01-23 08:00:00",
    "positions_to_fill": 4,
    "is_work_shift": true,
    "self_scheduling": true,
    "self_scheduling_requires_approval": true,
    "crewsense_eligible": true,
    "hide_open_slots": false,
    "color": "#CCCCCC",
    "location": {
        "address": "199 Northwest Hillcrest Drive",
        "city": "Grants Pass",
        "state": "OR",
        "country": "United States",
        "zip": "97526",
        "latitude": "42.45771410",
        "longitude": "-123.32473050"
    }
  },
  {
    "id": 124,
    "position": 4,
    "name": "Station 2",
    "date": "2014-01-22",
    "start": "2014-01-22 08:00:00",
    "end": "2014-01-23 08:00:00",
    "positions_to_fill": 3,
    "is_work_shift": true,
    "self_scheduling": true,
    "self_scheduling_requires_approval": true,
    "crewsense_eligible": true,
    "hide_open_slots": false,
    "color": "#CCCCCC",
    "location": null
  },
  ...
]

Returns all non-archived assignments of your organization. An assignment is archive if it has an Until date in the past, or is non-recurring and has already ended.

The return format is an array of JSON objects.

Properties

Name Description Format Default
id The unique identifier of the assignment integer
position The order in which assignments should be displayed integer
name Assignment name string
date The date this assignment started on date
start The full date/time of the start of the first occurrence of the assignment datetime
end The full date/time of the end of the first occurrence of the assignment datetime
positions_to_fill Number of required personnel on the assignment integer 1
is_work_shift If false, shifts in this assignment are ignored by the rest of the system boolean true
self_scheduling Are employees allowed to schedule themselves boolean false
self_scheduling_requires_approval Only if the above is true: if this is true, self scheduling requires the approval of an administrator boolean false
crewsense_eligible Should this assignment be analyzed with CrewSense Intelligence boolean false
hide_open_slots Condense the assignment in display, do not show vacant positions boolean false
color Background color of the assignment for display purposes, in HEX format string #RRGGBB #F5F4F2
location Detailed location information on the assignment. null if no location is set. location null

GET /assignments/{id}

{
    "id": 670,
    "position": 1,
    "name": "Station 1",
    "date": "2012-12-25 00:00:00",
    "start": "2012-12-25 08:00:00",
    "end": "2012-12-26 08:00:00",
    "positions_to_fill": 2,
    "is_work_shift": true,
    "self_scheduling": true,
    "self_scheduling_requires_approval": true,
    "crewsense_eligible": true,
    "hide_open_slots": false,
    "color": "#F5F4F2",
    "location": {
        "address": "199 Northwest Hillcrest Drive",
        "city": "Grants Pass",
        "state": "OR",
        "country": "United States",
        "zip": "97526",
        "latitude": "42.45771410",
        "longitude": "-123.32473050"
    }
}

Retrieve a specific assignment.

For the meaning and format of properties, see GET /assignments.

GET /assignments/{id}/groups

Returns assignment group label data

[
    {
        "id": "943",
        "name": "7367",
        "color": "#1700e6"
    }
]

GET /assignments/{id}/admins

[
    {
        "id": "953",
        "name": "John Smith",
        "href": "https://api.crewsense.com/v1/users/953"
    }
]

Returns data on who created the assignment

PUT /assignments/{id}/admins

PUT /assignments/{id}/admins

Updates admin data for who created the assignment

POST /assignments

Create a new Crew Scheduler Assignment.

Parameters

Name Description Format Required?
name Assignment name string yes
start The full date/time of the start of the first occurrence of the assignment 2016-11-28 07:00:00 yes
end The full date/time of the end of the first occurrence of the assignment 2016-11-28 19:00:00 yes
positions_to_fill Number of required personnel on the assignment integer yes
position The order in which assignments should be displayed integer
is_work_shift If false, shifts in this assignment are ignored by the rest of the system boolean
self_scheduling Are employees allowed to schedule themselves boolean
self_scheduling_requires_approval Only if the above is true: if this is true, self scheduling requires the approval of an administrator boolean
crewsense_eligible Should this assignment be analyzed with CrewSense Intelligence boolean
hide_open_slots Condense the assignment in display, do not show vacant positions boolean
color Background color of the assignment for display purposes, in HEX format string #RRGGBB

PATCH /assignments/{id}

PATCH /assignments/{id}

Updates assignment info

DELETE /assignments/{id}

delete /assignments/{id}

Deletes assignment

PUT /assignments/{id}/groups

PUT /assignments/{id}/groups

Updates assignment group label

DELETE /assignments/{id}/groups

DELETE /assignments/{id}/groups

Deletes ALL assignment group label(s)

DELETE /assignments/{id}/groups/{group_id}

DELETE /assignments/{id}/groups/{group_id}

Deletes specific assignment group label

POST /assignments/{id}/finalization

Example request

curl -v https://api.crewsense.com/v1/assignments/123/finalization \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d "date=2015-03-15" \
     -d "admin_id=111"

Example response (success)

{
    "success": true
}

Example response (already finalized on selected date)

{
    "error": "invalid_params",
    "status": 422,
    "error_message": [
        "Assignment (#123) has already been finalized on 2015-03-15."
    ]
}

Example response (invalid admin ID)

{
    "error": "invalid_params",
    "status": 422,
    "error_message": [
        "The selected admin id is invalid."
    ]
}

Finalize an assignment on a given date. POSTing to this endpoint will set the finalized flag — indicated by a green check mark in the Crew Scheduler — on the assignment on the date sent in the parameters.

Request parameters

Name Description Format Required?
date The date to finalize the assignment on. Date (YYYY-MM-DD) Y
admin_id ID of the admin user that finalizes the assignment. Integer Y

POST /finalization

Example request

curl -v https://api.crewsense.com/v1/finalization \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d "{ \"assignments\": [ { \"id\": 882, \"dates\": [\"2018-12-01\", \"2018-12-05\"] } ], \"admin_id\": 848 }"

Example response (success)

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "All finaliziations processed successfully."
}

Example response (already finalized on certain dates)

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "Finalizations processed with errors. See the error_messages field.",
    "success_messages": [
        "Assignment (#882) finalized on 2018-12-01."
    ],
    "error_messages": [
        "Assignment (#882) is already finalized on 2018-12-05."
    ]
}

Example response (none succeeded, future date selected)

{
    "error": "invalid_params",
    "status": 422,
    "error_message": [
        "Assignment (#882) Finalization is only allowed on past and current dates."
    ]
}

Example response (invalid admin ID)

{
    "error": "not found",
    "status": 404,
    "error_message": "No query results for model [User]."
}

Batch apply finalization on selected assignments on selected dates and/or date ranges. POSTing to this endpoint will set the finalized flag — indicated by a green check mark in the Crew Scheduler — on the assignments on the dates sent in the parameters.

Request parameters

Name Description Format Required?
assignments An array of objects containing assignment IDs and dates to finalize. See below array Y
admin_id ID of the admin user that finalizes the assignment. Integer Y

Assignment object format

You can select individual dates or a range of dates, or both, for each assignment. Dates in the dates array and between (inclusively) the start and end parameters will be merged and all processed.
Either dates or start and end are required.

Name Description Format Required?
id The ID of the assignment being finalized. integer Y
dates Array of dates to finalize in YYYY-MM-DD format. array N
start Start of the date range to finalize in YYYY-MM-DD format. date N
end End of the date range to finalize in YYYY-MM-DD format. The end date will be included in the dates finalized. date N

DELETE /assignments/{id}/finalization

Example request

curl -v https://api.crewsense.com/v1/assignments/123/finalization \
     --request DELETE \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d "{ \"date\": \"2015-03-15\" }"

Example response (success)

{
    "success": true
}

Example response (not finalized on selected date)

{
    "error": "invalid_params",
    "status": 422,
    "error_message": [
        "Assignment (#123) is not finalized on 2015-03-15."
    ]
}

Remove finalization of an assignment on a given date.

Request parameters

Name Description Format Required?
date The date to remove finalization from the assignment. Date (YYYY-MM-DD) Y

DELETE /finalization

Example request

curl -v https://api.crewsense.com/v1/finalization \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     --request DELETE \
     -d "{ \"assignments\": [ { \"id\": 882, \"dates\": [\"2018-12-01\", \"2018-12-05\"] } ], \"admin_id\": 848 }"

Example response (success)

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "All finaliziations processed successfully."
}

Example response (not finalized on certain dates)

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "Finalizations processed with errors. See the error_messages field.",
    "success_messages": [
        "Assignment (#882) finalized on 2018-12-01."
    ],
    "error_messages": [
        "Assignment (#882) is not finalized on 2018-12-05."
    ]
}

Example response (none succeeded, future date selected)

{
    "error": "invalid_params",
    "status": 422,
    "error_message": [
        "Assignment (#882) Finalization is only allowed on past and current dates."
    ]
}

Example response (invalid admin ID)

{
    "error": "not found",
    "status": 404,
    "error_message": "No query results for model [User]."
}

Batch remove finalization on selected assignments on selected dates and/or date ranges. DELETEing on this endpoint will remove the finalized flag — indicated by a green check mark in the Crew Scheduler — on the assignments on the dates sent in the parameters.

Request parameters

Name Description Format Required?
assignments An array of objects containing assignment IDs and dates to unfinalize. See below array Y
admin_id ID of the admin user that unfinalizes the assignment. Integer Y

Assignment object format

You can select individual dates or a range of dates, or both, for each assignment. Dates in the dates array and between (inclusively) the start and end parameters will be merged and all processed.
Either dates or start and end are required.

Name Description Format Required?
id The ID of the assignment being unfinalized. integer Y
dates Array of dates to unfinalize in YYYY-MM-DD format. array N
start Start of the date range to unfinalize in YYYY-MM-DD format. date N
end End of the date range to unfinalize in YYYY-MM-DD format. The end date will be included in the dates finalized. date N

Shifts

Allows you to retrieve, modify and create new CrewScheduler Shifts. Recurrence rules are not supported at this time, only one-off shifts can be processed with these endpoints.

GET /shifts

[
    {
        "id": 28871,
        "assignment_id": 670,
        "date": "2013-08-21",
        "start": "2013-08-21 07:00:00",
        "end": "2013-08-22 07:00:00",
        "user": {
            "id": 848,
            "name": "Boss Doe",
            "href": "https://api.crewsense.com/v1/users/848"
        },
        "scheduled_by": {
            "id": 98,
            "name": "Hass Brycen",
            "href": "https://api.crewsense.com/v1/users/98"
        },
        "work_type": {
            "id": 1,
            "href": "https://api.crewsense.com/v1/work_types/1",
            "name": "Regular time",
            "work_code": "REG001",
            "subtype_id": null
        },
        "labels":  [
            {
                "id": 123,
                "href": "https://api.crewsense.com/v1/labels/123",
                "label": "A Shift"
            }
        ],
        "qualifiers":  [
            {
                "id": 246027,
                "href": "https://api.crewsense.com/v1/qualifiers/246027",
                "shortcode": "FF-01",
                "name": "Firefighters"
            },
            {
                "id": 246027,
                "href": "https://api.crewsense.com/v1/qualifiers/246027",
                "shortcode": "TST",
                "name": "Test"
            }
        ],
        "traded_with": null,
        "from_callback": null,
        "notes": null,
        "created_at": "2018-03-06T08:45:00-08:00",
        "updated_at": "2018-03-06T08:45:00-08:00"
    },
    {
        "id": 35444,
        "assignment_id": 671,
        "date": "2013-08-18",
        "start": "2013-09-30 01:00:00",
        "end": "2013-09-30 08:00:00",
        "user": {
            "id": 848,
            "name": "Boss Doe",
            "href": "https://api.crewsense.com/v1/users/848"
        },
        "scheduled_by": {
            "id": 848,
            "name": "Boss Doe",
            "href": "https://api.crewsense.com/v1/users/848"
        },
        "work_type": {
            "id": 1,
            "href": "https://api.crewsense.com/v1/work_types/1",
            "name": "Regular time",
            "work_code": "REG001",
            "subtype_id": null
        },
        "labels": null,
        "qualifiers": null,
        "traded_with": null,
        "from_callback": null,
        "notes": null,
        "created_at": "2018-03-06T08:45:00-08:00",
        "updated_at": "2018-03-06T08:45:00-08:00"
    },
]

Retrieve all one-off non-recurring shifts of a certain user. This endpoint will be extended with more filtering options in the near future.

Parameters

Name Description Format Required?
user_id ID of the user to query shifts for integer yes

POST /shifts

Create a new single-day shift for a user.

Parameters

Name Description Format Required?
assignment_id Assignment id integer yes
user_id The ID of the user being assigned to a shift integer yes
date The full date of the calendar day the shift should appear on 2016-11-28 yes
start The full date/time of the start of the shift 2016-11-28 07:00:00 yes
end The full date/time of the end of the shift 2016-11-28 19:00:00 yes
work_type_id The ID of the work type to be used. See GET /work_types integer yes
work_subtype_id The ID of the work subtype to be used. See GET /work_types integer no
notes Any admin notes that should appear on the shift string no
from_callback The ID of the Callback the shift is a result of integer no
traded_with The ID of the user the shift is traded with integer no
labels An array of Label IDs to apply to the shift. See GET /labels array no
qualifiers An array of Qualifier IDs to apply to the shift. See GET /qualifiers array no

GET /shifts/{id}

See above for the output format

DELETE /shifts/{id}

Permanently remove all instances of a shift from the schedule.

PATCH /shifts/{id}

Example PATCH payload

{
    "date": "2018-03-01",
    "start": "2018-03-01 08:00:00",
    "end": "2018-03-01 20:00:00",
    "notes": "Changed to AM shift"
}

Update an existing shift. Provide any subset of the parameters described in the POST /shifts section. Currently, the date, start and end parameters are always required for a PATCH operation.

GET /shifts/{id}/qualifiers

See GET /shifts qualifiers key for the output format

POST /shifts/{id}/qualifiers

Replace the qualifiers on the shift. Provide an array of qualifier ID’s as the request body.

DELETE /shifts/{id}/qualifiers

Remove all qualifiers from the shift.

DELETE /shifts/{id}/qualifiers/{qualifierId}

Remove the qualifier in the second parameter from the shift.

GET /shifts/{id}/labels

See GET /shifts labels key for the output format

POST /shifts/{id}/labels

Replace the labels on the shift. Provide an array of qualifier ID’s as the request body.

DELETE /shifts/{id}/labels

Remove all labels from the shift.

DELETE /shifts/{id}/labels/{labelId}

Remove the label in the second parameter from the shift.

GET /work_types

Example request

curl -v https://api.crewsense.com/v1/work_types -G \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

[
    {
        "id": 5,
        "label": "Earned time off",
        "work_code": "ETO",
        "primary_color": "#3B4650",
        "secondary_color": "#FFFFFF",
        "excludes_from_callback": true,
        "position": 0,
        "href": "https://api.crewsense.com/v1/work_types/5"
    },
    {
        "id": 7,
        "label": "Comp time",
        "work_code": null,
        "primary_color": "#3B4650",
        "secondary_color": "#FFFFFF",
        "excludes_from_callback": true,
        "position": 1,
        "href": "https://api.crewsense.com/v1/work_types/7"
    }
]

Get all non-deleted work types in the system.

GET /work_types/{id}

Example request

curl -v https://api.crewsense.com/v1/work_types/5 -G \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

{
    "id": 5,
    "label": "Earned time off",
    "work_code": "ETO",
    "primary_color": "#3B4650",
    "secondary_color": "#FFFFFF",
    "excludes_from_callback": true,
    "position": 0,
    "href": "https://api.crewsense.com/v1/work_types/5"
}

Get a specific work type in the system.

GET /work_types/{id}/subtypes

Example request

curl -v https://api.crewsense.com/v1/work_types/2/subtypes -G \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

[
    {
        "id": 4,
        "work_type_id": 2,
        "label": "Holdover",
        "work_code": "HO"
    },
    {
        "id": 8,
        "work_type_id": 2,
        "label": "Mandatory",
        "work_code": "M-OT"
    }
]

Get all subtypes of a work type.

GET /work_subtypes

Example request

curl -v https://api.crewsense.com/v1/work_subtypes -G \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

[
    {
        "id": 4,
        "work_type_id": 2,
        "label": "Holdover",
        "work_code": "HO"
    },
    {
        "id": 8,
        "work_type_id": 2,
        "label": "Mandatory",
        "work_code": "M-OT"
    }
]

Get all non-deleted work subtypes in the system.

Visual Cycles

This endpoint will list all visual cycles an Organization is using in their CrewScheduler. Visual Cycles are used for displaying things like ‘FLSA cycles graphically in their calendars.

In the following sections, we try to introduce all the important data in the schedule resource.

GET /visual_cycles

An example of returned /visual_cycles data GET request looks like this:

[
   {
   "id": 2,
   "name": "FLSA Cycle #1",
   "start": "2017-01-01",
   "end": "2017-01-28",
   "color": "#f00",
   "text_color": "#fff",
   "created_by": 14690,
   "created_at": "2017-02-06 04:34:04",
   "deleted_by": null,
   "deleted_at": null
   }
,...
]

GET /visual_cycles

Optional Parameters

Passing the following parameters will return only visual cycles that fall within the start and end date

Name Description Format Required?
start Start date 2017-11-28 no
end End date 2017-11-29 no

GET /visual_cycles/{id}

GET /visual_cycles/{id}

POST /visual_cycles

POST /visual_cycles

Required Parameters

When creating a new visual cycle, the following are required

Name Description Format Required?
name name of visual cycle string y
start start date of cycle datetime y
end end date of cycle datetime y
color rgb value of background color rgbhex y
text_color rgb value of background color rgbhex y

PUT /visual_cycles/{id}

PUT /visual_cycles/{id}

DELETE /visual_cycles/{id}

DELETE /visual_cycles/{id}

Time Off

View, Edit and Create new Time Off entries in the system

GET /time_offs

Example request

curl -v https://api.crewsense.com/v1/time_offs \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

{
    "items": [
        {
            "id": 744837,
            "time_off_type": {
                "id": 6,
                "name": "Vacation",
                "work_code": "VAC001"
            },
            "user": {
                "id": 98,
                "name": "Brycen Doe",
                "href": "https://api.crewsense.com/v1/users/98"
            },
            "admin": {
                "id": 34942,
                "name": "Oliver CrewSense",
                "href": "https://api.crewsense.com/v1/users/34942"
            },
            "start": "2017-07-10 07:00:00",
            "end": "2017-07-11 07:00:00",
            "length": 24,
            "real_length": 23.5,
            "status": 1,
            "request_date": "2017-07-10T08:19:57-07:00",
            "approval_date": "2017-07-10T11:12:33-07:00",
            "acknowledgement_date": null,
            "user_note": null,
            "traded_with": {
                "id": 848,
                "name": "Boss Doe",
                "href": "https://api.crewsense.com/v1/users/848"
            }
        }
    ],
    "metadata": {
        "start": "2018-10-01 00:00:00",
        "end": "2019-01-01 00:00:00",
        "page_start": "2018-10-01 00:00:00",
        "page_end": "2018-11-01 00:00:00",
        "links": {
            "prev": null,
            "next": "http://api.crewsense.local/v1/time_offs?start=2018-10-01+00%3A00%3A00&end=2019-01-01+00%3A00%3A00&after=2018-11-01+00%3A00%3A00"
        }
    }
}

Get all time off entries for a given date range.

Results of this endpoint are paginated. If the request is for more than a months data, the API will return data for the first month, and provide links for the next page of the dataset. If the next link is empty, that result set was the last page of the data.

Required Parameters

Field Description Type
start Start date of query timeframe datetime
end End date of query timeframe datetime

Metadata

Field Description Type
start Start of the originally requested date period datetime
end End of the originally requested date period datetime
page_start Start date of data returned on the current page datetime
page_end End date of data returned on the current page datetime
links URLs to request to get the previous and next page of the dataset array

GET /time_offs/{id}

Example request

curl -v https://api.crewsense.com/v1/time_offs/744837 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

{
    "items": [
        {
            "id": 744837,
            "time_off_type": {
                "id": 6,
                "name": "Vacation",
                "work_code": "VAC001"
            },
            "user": {
                "id": 98,
                "name": "Brycen Doe",
                "href": "https://api.crewsense.com/v1/users/98"
            },
            "admin": {
                "id": 34942,
                "name": "Oliver CrewSense",
                "href": "https://api.crewsense.com/v1/users/34942"
            },
            "start": "2017-07-10 07:00:00",
            "end": "2017-07-11 07:00:00",
            "length": 24,
            "real_length": 23.5,
            "status": 1,
            "request_date": "2017-07-10T08:19:57-07:00",
            "approval_date": "2017-07-10T11:12:33-07:00",
            "acknowledgement_date": null,
            "user_note": null,
            "traded_with": {
                "id": 848,
                "name": "Boss Doe",
                "href": "https://api.crewsense.com/v1/users/848"
            }
        }, {
            "id": 744837,
            "time_off_type": {
                "id": 6,
                "name": "Vacation",
                "work_code": "VAC001"
            },
            "user": {
                "id": 98,
                "name": "Brycen Doe",
                "href": "https://api.crewsense.com/v1/users/98"
            },
            "admin": {
                "id": 34942,
                "name": "Oliver CrewSense",
                "href": "https://api.crewsense.com/v1/users/34942"
            },
            "start": "2017-07-11 07:00:00",
            "end": "2017-07-12 07:00:00",
            "length": 24,
            "real_length": 23.5,
            "status": 1,
            "request_date": "2017-07-10T08:19:57-07:00",
            "approval_date": "2017-07-10T11:12:33-07:00",
            "acknowledgement_date": null,
            "user_note": null,
            "traded_with": {
                "id": 848,
                "name": "Boss Doe",
                "href": "https://api.crewsense.com/v1/users/848"
            }
        }
    ],
    "metadata": []
}

Get all occurrences of a specific time off entry.

POST /time_offs

POST /time_offs

POST /time_offs example JSON body:

{
    "user_id": 138,
    "admin_ids": [848, 6461],
    "start_date": "2016-11-02 08:00:00",
    "end_date": "2016-11-03 08:00:00",
    "time_off_type_id": 456,
    "user_note": "I would like to go to Hawaii",
    "status": 1
}

Create a new Time Off entry in system

Query Parameters

Field Description Required?
user_id user id of employee Y
admin_ids user id of approving admin Y
start_date start date / time of time off entry Y
end_date end date / time of time off entry Y
time_off_type_id id of time off type to use Y
status pending or approved? boolean (0 = pending, 1 = approved) N
user_note brief note; Max limit 1000 characters N

DELETE /time_offs/{id}

Example request

curl -v https://api.crewsense.com/v1/time_offs/1234 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -X DELETE

Example response (success)

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "Time Off removed successfully."
}

Example response (not found)

{
    "error": "not found",
    "status": 404,
    "error_message": "No query results for model [TimeOff]."
}

Delete a time off entry from the system.

POST /time_offs/{id}/deny

POST /time_offs/{id}/deny

Deny time off request

POST /time_offs/{id}/approve

POST /time_offs/{id}/deny

Approve time off request

GET /time_off_types

Get all non-deleted time off types in the system.

GET /time_off_types

GET /time_off_types example response

[
   {
      "id": "5",
      "label": "Sick",
      "work_code": "SL",
      "required_buffer": "0.00",
      "instance_limit": "1",
      "primary_color": "#2474a9",
      "secondary_color": "#FFFFFF",
      "force_include": true,
      "forward": false,
      "href": "https://api.crewsense.com/v1/time_off_types/5"
   }
   {
      "id": "6",
      "label": "Vacation",
      "work_code": "VAC",
      "required_buffer": "0.00",
      "instance_limit": "0",
      "primary_color": "#3f5647",
      "secondary_color": "#FFFFFF",
      "force_include": false,
      "forward": true,
      "href": "https://api.crewsense.com/v1/time_off_types/6"
   }
]

POST /time_off_types

Create new time off type in the system.

POST /time_off_types

Query Parameters

Field Description Type
id Unique identifier of the time off type integer
href Link to full object string (URL)
label Name of the time off type string
work_code Shortcode of the time off type string
required_buffer Hours needed between request and start of the time off entry decimal
instance_limit Max. allowed number of this type in a yea integer
primary_color Main color of the type (background color) RGB hex
secondary_color Text color of the type RGB hex
force_include Ignore time off of this type in callbacks boolean
forward Forward time off of this type to other admins if not handled boolean

Accruals

GET /accruals

GET /accruals

GET /accruals example response

[
    {
        "time_off_type": {
            "id": "37",
            "name": "Sick"
        },
        "accrual_type": "Accrues 6 hours every pay period (max. 150 hours)"
    },
    {
        "time_off_type": {
            "id": "38",
            "name": "Vacation"
        },
        "accrual_type": "Accrues 144 hours every year (max. 300 hours)"
    },
]

View all accrual profiles for company

GET /users/{user_id}/timeoff/accrual/profile

GET /users/1234/timeoff/accrual/profile example:

[
   {
      "time_off_type": {
         "id": 5,
         "name": "Sick"
      },
      "accrual_type": "Accrues 10 hours every 28 days"
   },
   {
      "time_off_type": {
         "id": 6,
         "name": "Vacation"
      },
      "accrual_type": "Accrues one hour every 10 hours worked (max. 12 hours)"
   },
   {
      "time_off_type": {
         "id": 7,
         "name": "Earned Time"
      },
      "accrual_type": "No automatic accrual"
   },

   ...

]

Return the accrual profiles for each user

GET /users/{user_id}/timeoff/accrual/profile

GET /users/{user_id}/timeoff/accrual/bank

GET /users/{user_id}/timeoff/accrual/bank

GET /users/{user_id}/timeoff/accrual/bank example response

[
    {
        "hours": 592.5,
        "time_off_type": {
            "id": "5",
            "name": "Sick"
        }
    },
    {
        "hours": 746.7104,
        "time_off_type": {
            "id": "6",
            "name": "Vacation"
        }
    }
]

Returns all accrual balances a user

POST /users/{user_id}/timeoff/accrual/bank/{id}

POST /users/{user_id}/timeoff/accrual/bank

Updates users accrual bank balance. Reference time_off_type_id

Required Parameters

Field Description Type Required?
time_off_type_id You can issue a GET request to /time_off_types to get a list of your types in the system, and reference the id attribute in that list to find this ID integer y
hours The number of hours to add to their bank. If you want to deduct hours, provide a negative number. integer y
admin_id The User ID of the user issuing the manual adjustment. integer y
notes Any notes you might want to save for the manual entry. string n

Trades

GET /trades

GET /trades

GET /trades example response

   [
        {
            "id": "44799",
            "requesting_user": {
                "id": "956",
                "name": "Vincent Ownbey",
                "href": "https://api.crewsense.com/v1/users/956"
            },
            "request_date": "2016-05-10T17:16:15-07:00",
            "start": "2016-06-17T07:00:00-07:00",
            "end": "2016-06-18T07:00:00-07:00",
            "swap_start": "2017-07-14T13:21:18-07:00",
            "swap_end": "2017-07-14T13:21:18-07:00",
            "status": "filled"
        },

GET /trades/{id}/users

GET /trades/{id}/users

List all users who were apart of a specific trade and their responses / status

POST /trades

POST /trades

Initiate a new trade in the system

GET /trades example response

   [
        {
            "requesting_user": "956",
            "start": "2016-06-17 07:00:00",
            "end": "2016-06-18 07:00:00",
            "accepting_user_id": "145",
            "approving_user_id": "123"
        },

Required Parameters

Field Description Type Required?
requesting_user the person who requested the trade integer y
start start date / time of trade 2016-06-17 07:00:00 y
end end date 2016-06-18 07:00:00 y
approving_user_id who approved the trade integer y

PATCH /trades/{id}

PATCH /trades/{id}

DELETE /trades/{id}

DELETE /trades/{id}

Deletes a trade from the system

PUT /trades/{id}

PUT /trades/{id}

Labels

GET /labels

GET /labels

Receive a list of all crew scheduler labels available for the company.

GET /labels

[
   {
      "id": "1773",
      "label": "CPT",
      "color": "#CCCCCC",
      "text_color": "#333333",
      "position": "1"
   },
   {
      "id": "1774",
      "label": "ENG",
      "color": "#ff0000",
      "text_color": "#ffffff",
      "position": "2"
   }
]

Query Parameters

Field Description Type
id Unique identifier of the label integer
label The text appearing on the label string
color The background color of the label RGB hex
text_color The text color of the label RGB hex
position Relative CrewScheduler position order of this label integer

GET /labels/{id}

example: GET /labels/1773

Receive the details of one particular label.

GET /labels

{
   "id": "1773",
   "label": "CPT",
   "color": "#CCCCCC",
   "text_color": "#333333",
   "position": "1"
}

POST /labels

Create a new crew scheduler label in the system.

POST /labels

Parameters

Field Description Type Required?
label the text on the label string y
color the background color of the label, in HEX format (#RRGGBB) rgbhex y
text_color the text color of the label, in HEX format (#RRGGBB) rgbhex y
position crewscheduler ordering position integer n

POST /labels/{id}

Change an existing crew scheduler label in the system.

POST /labels/{id}

Parameters

Field Description Type Required?
label the text on the label string y
color the background color of the label, in HEX format (#RRGGBB) rgbhex y
text_color the text color of the label, in HEX format (#RRGGBB) rgbhex y
position crewscheduler ordering position integer n

DELETE /labels/{id}

Remove an existing crew scheduler label from the system.

DELETE /labels/{id}

Filters

GET /filters

GET /filters example response:

[
   {
      "id": "7",
      "label": "Rescue Certified",
      "created_on": "2014-10-29T02:17:51-0700",
      "user": {
         id: "848",
         name: "John Doe"
      }
   },
   {
      "id": "8",
      "label": "Dive Team",
      "created_on": "2014-10-30T12:04:01-0700",
      "user": {
         id: "848",
         name: "John Doe"
      }
   }
]

Receive a list of all active specialty classification filters

GET /filters

Query Parameters

Field Description Type
id Unique identifier of the filter integer
label The name of the filter string
created_on Timestamp of the creation of this filter timestamp
user The user who created this resource User

GET /filters/{id}

GET /filters/{id}

GET /filters/7 example response:

{
   "id": "7",
      "label": "Rescue Certified",
      "created_on": "2014-10-29T02:17:51-0700",
      "deleted": "0",
      "user": {
         id: "848",
         name: "John Doe"
      }
}

The deleted key indicates if the filter has been deleted, 0 = active, 1= deleted.

POST /filters

Create a new specialty classification filter in the system. Required fields:

POST /filters

Parameters

Field Description Type Required?
label the name of the new specialty classification filt string y

POST /filters/{id}

Change an existing specialty classification filter in the system. Required fields:

POST /filters/{id}

Parameters

Field Description Type Required?
label the new name of the new specialty classification filt string y

DELETE /filters/{id}

Remove an existing specialty classification filter from the system.

DELETE /filters/{id}

Groups

GET /groups

GET /groups example response:

[
   {
      "id": "1",
      "label": "A Shift"
   },
   {
      "id": "2",
      "label": "B Shift"
   }
]

Receive a list of all groups

GET /groups

POST /groups

Create a new group in the system. Required fields:

POST /groups

Parameters

Field Description Type Required?
name the name of the new group string y

Lists

GET /lists

Example request

curl -v https://api.crewsense.com/v1/lists \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

[
    {
        "id": 101,
        "name": "Captain",
        "max_consecutive_hours": 0,
        "weekly_limit": 0,
        "monthly_limit": 0,
        "yearly_limit": 1560,
        "position": 1
    },
    {
        "id": 2669,
        "name": "Firefighter",
        "max_consecutive_hours": 48,
        "weekly_limit": 0,
        "monthly_limit": 0,
        "yearly_limit": 0,
        "position": 2
    }
]

Get a list of all active CallBack Lists in the system.
Alias: GET /titles

Parameters

Name Description Type
id Unique identifier of the list. integer
name Name of the list. string
max_consecutive_hours Maximum number of consecutive hours allowed for users of this list. integer
weekly_limit Maximum number of hours allowed in a week for users of this list. integer
monthly_limit Maximum number of hours allowed in a month for users of this list. integer
yearly_limit Maximum number of hours allowed in a year for users of this list. integer
position The ordered position of the list among all lists. integer

GET /lists/{id}

Example request

curl -v https://api.crewsense.com/v1/lists/101 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

{
    "id": 101,
    "name": "Captain",
    "max_consecutive_hours": 0,
    "weekly_limit": 0,
    "monthly_limit": 0,
    "yearly_limit": 1560,
    "position": 1,
    "deleted": false
}

Retrieve a list from the system.
Alias: GET /titles/{id}

Parameters

Name Description Type
id Unique identifier of the list. integer
name Name of the list. string
max_consecutive_hours Maximum number of consecutive hours allowed for users of this list. integer
weekly_limit Maximum number of hours allowed in a week for users of this list. integer
monthly_limit Maximum number of hours allowed in a month for users of this list. integer
yearly_limit Maximum number of hours allowed in a year for users of this list. integer
position The ordered position of the list among all lists. integer
deleted Is the list deleted and no longer usable? boolean

Users

GET /users

GET /users

[
   {
      "user_id": 1234,
      "employee_id": "DEV123",
      "username": "olinagy",
      "first_name": "Oliver",
      "last_name": "Nagy",
      "full_name": "Oliver Nagy",
      "role": "Deputy",
      "avatar_url": "https://s3-us-west-2.amazonaws.com/cbs-file-storage/company-8/avatars/586cf2dd6db20-boss_doe-thumb.jpg",
      "date_of_hire": "2011-03-04",
      "date_of_birth": "1987-07-04",
      "accrual_start_date": "2012-05-05",
      "emails": [
         "oli.nagy@example.com",
         "oli.nagy@otherexample.net"
      ],
      "phone_numbers": [
         "5555555555",
         "1231231232"
      ],
      "accrual_track": {
         "id": 4,
         "name": "Firefighter"
      },
      "accrual_profile": {
         "id": 5,
         "name": "Firefighter 5-10 years"
      }
   },
   ...
]

GET /users

List all non-deleted, active users of the company.

Parameters

Field Description Type Required?
employee_id The employee ID of the employee being searched for string n

GET /users/{user_id}

GET /users/{user_id}

Returns specific user info. This call will retrieve any extra fields that you might have set up for the user in System Settings.

GET /users/{user_id}

{
   "user_id": 1234,
   "employee_id": "DEV123",
   "username": "olinagy",
   "first_name": "Oliver",
   "last_name": "Nagy",
   "full_name": "Oliver Nagy",
   "role": "Deputy",
   "avatar_url": "https://s3-us-west-2.amazonaws.com/cbs-file-storage/company-8/avatars/586cf2dd6db20-boss_doe-thumb.jpg",
   "date_of_hire": "2011-03-04",
   "date_of_birth": "1987-07-04",
   "accrual_start_date": "2012-05-05",
   "emails": [
      "oli.nagy@example.com",
      "oli.nagy@otherexample.net"
   ],
   "phone_numbers": [
      "5555555555",
      "1231231232"
   ],
    "fields": [
        {
            "id": 1,
            "label": "Retired?",
            "value": "1"
        },
        {
            "id": 2,
            "label": "Gender",
            "value": "Male"
        },
        {
            "id": 3,
            "label": "Eligible for leave",
            "value": "0"
        }
    ],
    "accrual_track": {
      "id": 4,
      "name": "Firefighter"
    },
    "accrual_profile": {
      "id": 5,
      "name": "Firefighter 5-10 years"
    }
}

GET /users/{user_id}/titles

GET /users/{user_id}/titles

Returns all CallBack lists user is associated with

PUT /users/{user_id}/titles

PUT /users/{user_id}/titles example request

{
    "ids": [101, 104]
}

PUT /users/{user_id}/titles example response

{
    "success": true
}

PUT /users/{user_id}/titles

Update the list of Callback Lists the user is associated with. Pass the IDs in the ids parameter in the request body. The user’s current Callback Lists will be overwritten with the ones provided in the parameter.

GET /users/{user_id}/filters

GET /users/{user_id}/filters

Returns all Speciality Filers user is associated with

PUT /users/{user_id}/filters

PUT /users/{user_id}/filters example request

{
    "ids": [10, 11, 55, 132]
}

PUT /users/{user_id}/filters example response

{
    "success": true
}

PUT /users/{user_id}/filters

Update the list of Specialty Filters the user is associated with. Pass the IDs in the ids parameter in the request body. The user’s current Specialty Filters will be overwritten with the ones provided in the parameter.

GET /users/{user_id}/groups

GET /users/{user_id}/groups

Returns all Groups user is associated with

GET /users/{user_id}/groups

[
    {
        "id": 2097,
        "name": "Platoon 1"
    },
    {
        "id": 2128,
        "name": "A Shift"
    }
]

PUT /users/{user_id}/groups

PUT /users/{user_id}/groups example request

{
    "ids": [2097, 2128]
}

PUT /users/{user_id}/groups example response

{
    "success": true
}

PUT /users/{user_id}/groups

Update the list of Groups the user is associated with. Pass the group IDS in the ids parameter in the request body. The user’s current groups will be overwritten with the ones provided in the parameter.

GET /users/{user_id}/qualifiers

Example request

curl -v https://api.crewsense.com/v1/users/848/qualifiers \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

[
    {
        "id": 7,
        "name": "Captains",
        "shortcode": "CPT",
        "ranking": 1
    },
    {
        "id": 8,
        "name": "Firefighters",
        "shortcode": "FF-01",
        "ranking": 2
    }
]

Returns all qualifiers associated to the user.

Response parameters

Name Description Type
id Unique identifier of the qualifier. integer
name Name of the qualifier string
shortcode Shortcode of the qualifier string
ranking The position of the qualifier among the user’s qualifiers. May be zero if the order of the user’s qualifiers was never changed. integer

POST /users/{user_id}/qualifiers

Example request

curl -v https://api.crewsense.com/v1/users/848/qualifiers \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d "{ \"id\": 9, \"ranking\": 2 }"

Example response

{
    "success": true,
    "code": 201,
    "status": "created",
    "message": "Added user Boss Doe to qualifier Chief."
}

Adds a qualifier to the user.

Request parameters

Name Description Type Required
id Unique identifier of the qualifier. integer Y
ranking The position of the qualifier among the user’s qualifiers. If not provided, the qualifier will go on the end of the user’s qualifier list. integer N

DELETE /users/{user_id}/qualifiers/{id}

Example request

curl -v https://api.crewsense.com/v1/users/848/qualifiers/32 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -X DELETE

Example response

{
    "success": true,
    "code": 200,
    "status": "o",
    "message": "Removed user Boss Doe from qualifier Chief."
}

Removes a qualifier from the user.

PUT /users/{user_id}/qualifiers

Example request

curl -v https://api.crewsense.com/v1/users/848/qualifiers \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -X PUT
     -d "{ \"ids\": [{ \"id\": 9, \"ranking\": 1 }, { \"id\": 10, \"ranking\": 2 }] }"

Example response

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "Replaced user qualifiers."
}

Replaces user qualifiers with the provided list of qualifiers.

Request parameters

The request should have an ids containing an array of objects described below:

Name Description Type Required
id Unique identifier of the qualifier. integer Y
ranking The position of the qualifier among the user’s qualifiers. If not provided, the qualifier will go on the end of the user’s qualifier list. integer N

PUT /users

PUT /users

PUT /users example JSON body

{
   "employee_id": "DEV123",
   "username": "olinagy",
   "first_name": "Oliver",
   "last_name": "Nagy",
   "full_name": "Oliver Nagy",
   "role": "Deputy",
   "date_of_hire": "2011-03-04",
   "date_of_birth": "1987-07-04",
   "phone": "5555555555",
   "mail": "info@example.com"
}

Create a new user. Send JSON data in the body

Parameters

Field Description Type Required?
username the username for the user string y
first_name first name string y
last_name last name string y
mail email address string y
password password for the user string y
employee_id internal employee id # integer n
phone_numbers phone number for user (format: 5555555555) integer n
role permission role for user string integer
date_of_hire Hire/promotion date in YYYY-MM-DD format date n
date_of_birth Birthdate in YYYY-MM-DD format date n

PATCH /users/{user_id}

PATCH /users/{user_id} example:

{
    "first_name": "Oliver",
    "last_name": "Nagy",
    "accrual_profile": {
        "id": 7
    },
    "accrual_track": {
        "id": 112
    },
    "accrual_start_date": "2017-05-11"
}

PATCH /users/{user_id}

Update a user with the user_id. Send JSON data in the request body. You only need to send data that you want to update.

GET /users/{user_id}/time_offs

Retrieve time off entries for a user

GET /users/{user_id}/time_offs

GET /users/{user_id}/time_offs example response:

[
    {
        "id": "744837",
        "time_off_type": {
            "id": "6",
            "name": "Vacation",
            "work_code": "VAC001"
        },
        "user": {
            "id": "98",
            "name": "Brycen Doe",
            "href": "/users/98"
        },
        "admin": {
            "id": "34942",
            "name": "Oliver CrewSense",
            "href": "/users/34942"
        },
        "start": "2017-07-10 07:00:00",
        "end": "2017-07-11 07:00:00",
        "rrule": null,
        "status": "1",
        "request_date": "2017-07-10T08:19:57-07:00",
        "approval_date": "1969-12-31T16:00:00-08:00",
        "acknowledgement_date": "1969-12-31T16:00:00-08:00",
        "user_note": null,
        "traded_with": null
    }
]

Optional Parameters

The start/end parameters filter the results to time off entries occurring inside the selected timeframe.

Field Description Type
start Start date of query timeframe. Defaults to one month ago. datetime
end End date of query timeframe. Defaults to the current date. datetime

POST /users/{user_id}/time_offs

Request time off for user

POST /users/{user_id}/time_offs

PATCH /users/{user_id}/time_offs/{id}

Edit time off request Data

PATCH /users/{user_id}/time_offs/{id}

Certifications

These endpoints allow you to create, update and delete certifications. You can also use them to add or remove them to users.

GET /certifications

Example request

curl -v https://api.crewsense.com/v1/certifications \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

[
    {
        "id": 1,
        "name": "Emergency",
        "cert_id": "EMERG",
        "created_by": {
            "id": 98,
            "name": "Hass Brycen",
            "href": "https://api.crewsense.com/v1/users/98"
        }
    },
    {
        "id": 2,
        "name": "First Responder",
        "cert_id": "FRS",
        "created_by": {
            "id": 98,
            "name": "Hass Brycen",
            "href": "https://api.crewsense.com/v1/users/98"
        }
    }
]

Returns all non-deleted Certifications in system.

GET /certifications/{id}

Example request

curl -v https://api.crewsense.com/v1/certifications/2 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

{
    "id": 2,
    "name": "First Responder",
    "cert_id": "FRS",
    "created_by": {
        "id": 98,
        "name": "Hass Brycen",
        "href": "https://api.crewsense.com/v1/users/98"
    }
}

Returns a specific Certification by ID.

POST /certifications

Example request

curl -v https://api.crewsense.com/v1/certifications \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -H "Content-Type: application/json" \
     -d '{ "name": "First Responder", "cert_id": "FRS", "created_by": 123 }'

Example response

{
    "success": true,
    "code": 201,
    "status": "created",
    "message": "Added new certification First Responder.",
    "id": 321
}

Create a new certification. The id received in the response can be used to add the certification to users.

Request Parameters

Key Description Type Required
name The name of the new certification string Y
cert_id The shortcode for the new certification. string Y
created_by The ID of the user that should be indicated as the creator of the certification. integer Y

PUT /certifications/{id}

Example request

curl -v https://api.crewsense.com/v1/certifications/321 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -H "Content-Type: application/json" \
     --request PUT \
     -d '{ "name": "Second Responder", "cert_id": "SRS" }'

Example response

{
    "success": true,
    "code": 200,
    "status": "created",
    "message": "Updated certification Second Responder.",
    "id": 321
}

Updates a certification. Only provided fields will be updated, other fields will remain unchanged.

Request Parameters

Key Description Type Required
name The name of the certification string N
cert_id The shortcode for the certification. string N

DELETE /certifications/{id}

Example request

curl -v https://api.crewsense.com/v1/certifications/321 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -H "Content-Type: application/json" \
     --request DELETE 

Example response

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "Deleted certification First Responder."
}

Example response (already deleted)

{
    "error": "bad_request",
    "status": 400,
    "error_message": "Certification already deleted."
}

Deletes a certification. Certifications in the system are soft-deleted, which means they can be restored alongside their users in an event of accidental deletion. They won’t show up in GET requests after deleting.

GET /users/{user_id}/certifications

GET /users/{user_id}/certifications

Returns all certifications of a user in the system.

GET /users/{user_id}/certifications/{id}

GET /users/{user_id}/certifications/{id}

Returns specific certification info for a user.

POST /users/{user_id}/certifications

POST /users/{user_id}/certifications

Add a certification to a user in the system.

DELETE /users/{user_id}/certifications/{id}

DELETE /users/{user_id}/certifications/{id}

Deletes a certification of a user in the system.

PUT /users/{user_id}/certifications/{id}

PUT /users/{user_id}/certifications/{id}

Updates a certification record for an employee.

DELETE /users/{user_id}/certifications

GET /users/{user_id}/certifications

Deletes all certifications of a user

POST /users/{user_id}/certifications/{id}/file

POST /users/{user_id}/certifications/{id}/file

Uploads file (pdf, jpeg or doc) of certification for user

Logs

Query the system logs

Whenever any change is made in the system, we add a system log entry. The endpoints below allow access to these system logs.

We return 50 log entries per page. The prev and next links provide pagination through all of the system logs.

GET /logs

GET /logs example:

{
  "data": [
    {
      "log_id": "3359725",
      "created": "2016-10-21T20:49:50-0700",
      "event_description": "Brandon Rigaud logged in.",
      "user": {
        "id": "965",
        "name": "Brandon Rigaud",
        "href": "https://api.crewsense.com/v1/users/965"
      }
    },
    {
      "log_id": "3359722",
      "created": "2016-10-21T20:49:08-0700",
      "event_description": "Brandon CrewSense changed shift for Tim Stacy: 7308 now from 10-23-16 7:00 am to 10-24-16 7:00 am, originally from 10-23-16 7:00 am to 10-24-16 7:00 am Work Type: Overtime",
      "user": {
        "id": "34941",
        "name": "Brandon CrewSense",
        "href": "https://api.crewsense.com/v1/users/34941"
      }
    }...
]
}

GET /logs

Returns system log data.

Can pass optional after parameter to return only logs after specific date / time.

GET /logs/after

Query Parameters

Field Description Required?
after date / time to return logs from n

CallBacks

GET /callbacks

GET /callbacks sample response:

{
    "data": [ 
        {
            "id": 123456,
            "title": {
                "id": 456,
                "name": "Firefighter"
            },
            "initiated_by": {
                "id": 848,
                "name": "John Doe"
            },
            "start": "2016-11-09 08:00:00",
            "end": "2016-11-10 08:00:00",
            "positions_to_fill": 2,
            "scheduled_to": "2016-11-05T06:30:00-07:00",
            "started_at": "2016-11-05T06:30:00-07:00",
            "ended_at": "2016-11-05T07:12:44-07:00",
            "deadline": "2016-11-05T10:00:00-07:00"
            "status": "filled"
        },{
            "id": 123456,
            "title": {
                "id": 456,
                "name": "Firefighter"
            },
            "initiated_by": {
                "id": 848,
                "name": "John Doe"
            },
            "start": "2016-11-09 08:00:00",
            "end": "2016-11-10 08:00:00",
            "positions_to_fill": 2,
            "scheduled_to": "2016-11-05T06:30:00-07:00",
            "started_at": "2016-11-05T06:30:00-07:00",
            "ended_at": "2016-11-05T07:12:44-07:00",
            "deadline": "2016-11-05T10:00:00-07:00"
            "status": "filled"
        }
    ],
    "pagination": {
        "prev": "https://api.crewsense.com/v1/callbacks?offset=50",
        "next": "https://api.crewsense.com/v1/callbacks?offset=150"
    }
}

GET /callbacks

Returns CallBacks in the system

Optional Parameters

Passing the following parameters will return only callbacks that fall within the start and end date

Name Description Format Required?
start Start date 2017-11-28 07:00:00 no
end End date 2017-11-29 07:00:00 no

GET /callbacks/{id}

GET /callbacks/123456 example

      {
            "id": 123456,
            "title": {
                "id": 456,
                "name": "Firefighter"
            },
            "initiated_by": {
                "id": 848,
                "name": "John Doe"
            },
            "start": "2016-11-09 08:00:00",
            "end": "2016-11-10 08:00:00",
            "positions_to_fill": 2,
            "scheduled_to": "2016-11-05T06:30:00-07:00",
            "started_at": "2016-11-05T06:30:00-07:00",
            "ended_at": "2016-11-05T07:12:44-07:00",
            "deadline": "2016-11-05T10:00:00-07:00",
            "status": "filled"
        }

GET /callbacks/{id}/

Returns data for a specific CallBack

GET /callbacks/{id}/users

GET /callbacks/123456/users example response

[
  {
    "id": "972",
    "position": "1",
    "status": "denied",
    "contact_method": "Mobile App",
    "contact_time": "2016-11-22 12:52:21",
    "response_time": "2016-11-22 13:00:39",
    "start_time": null,
    "end_time": null,
    "uses_opportunity": "1",
    "do_not_disturb": "0",
    "auto_accepted": "0"
  },
  {
    "id": "973",
    "position": "2",
    "status": "no answer",
    "contact_method": "Text (SMS)",
    "contact_time": "2016-11-22 12:58:25",
    "response_time": null,
    "start_time": null,
    "end_time": null,
    "uses_opportunity": "1",
    "do_not_disturb": "0",
    "auto_accepted": "0"
  }
]

GET /callbacks/{id}/users

Returns data for specific users of the CallBack

Signup Board

GET /signup_events

Example request

curl -v https://api.crewsense.com/v1/signup_events \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example request (only active signup events)

curl -v https://api.crewsense.com/v1/signup_events -G \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d "status=active"

Example response (no filters applied)

[
    {
        "id": 5,
        "work_type_id": 1,
        "work_subtype_id": null,
        "title": "May the 4th be with you",
        "start": "2018-05-04 08:00:00",
        "end": "2018-05-05 08:00:00",
        "description": "<p>Testing!</p>",
        "created_by": 34942,
        "created_at": "2018-11-01T09:34:45-07:00",
        "modified_by": 34942,
        "modified_at": "2018-11-01T09:34:45-07:00",
        "employees_needed": 2,
        "status": "partially_filled"
    },
    {
        "id": 6,
        "work_type_id": 2,
        "work_subtype_id": 8,
        "title": "Cinco de Cuatro",
        "start": "2018-05-04 08:00:00",
        "end": "2018-05-05 08:00:00",
        "description": "<p>Chickens don't CLAP!</p>",
        "created_by": 34942,
        "created_at": "2018-09-05T05:32:36-07:00",
        "modified_by": 34942,
        "modified_at": "2018-09-05T05:32:36-07:00",
        "employees_needed": 10,
        "status": "active"
    }
]

Retrieve Signup Events.

Parameters

Name Description Type
id Unique identifier of the Signup Event. integer
work_type_id The ID of the work type used for signed up employees. integer
work_subtype_id The ID of the subtype of the work type (if any) integer
title A descriptive name for the Signup Event. string
start Event start datetime
end Event end datetime
description Longer description of the Signup Event in HTML string
created_by The user ID of the person creating the event. integer
created_at ISO8601 timestamp of the creation date ISO datetime
modified_by The user ID of the person who last modified the event. integer
modified_at ISO8601 timestamp of the last modification date ISO datetime
employees_needed The number of employees required to sign up before the event is closed. integer
status The current status of the Signup Event. One of active, partially_filled, filled, not_filled, deleted

By default, all but deleted events will be returned from the system. You can apply some parameters to refine the returned result set:

Query Parameters

Name Description Type
deleted If set and has a positive value (ie. 1, true), we only return deleted events. boolean
archived If set and has a positive value (ie. 1, true), we only return non-deleted, non-active events. boolean
status If set, we only return non-deleted events of the given status. One of active, partially_filled, filled, not_filled. string
start If set, we only return non-deleted Signup Events with a start value greater than or equal to the given timestamp datetime
end If set, we only return non-deleted Signup Events with an end value less than or equal to the given timestamp datetime

start and end can be used together to query a time period for Signup Events.

GET /signup_events/{id}

Example request

curl -v https://api.crewsense.com/v1/signup_events/5 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

{
    "id": 5,
    "work_type_id": 1,
    "work_subtype_id": null,
    "title": "May the 4th be with you",
    "start": "2018-05-04 08:00:00",
    "end": "2018-05-05 08:00:00",
    "description": "<p>Testing!</p>",
    "created_by": 34942,
    "created_at": "2018-11-01T09:34:45-07:00",
    "modified_by": 34942,
    "modified_at": "2018-11-01T09:34:45-07:00",
    "deleted_by": 34942,
    "deleted_at": "2018-11-05T11:24:23-07:00",
    "employees_needed": 2,
    "status": "deleted"
}

Return a specific Signup Event of the company. This endpoint will return data even for deleted Signup Events for auditing reasons, in which case deleted_by and deleted_at will not be null. Other parameters match those of a single value from the GET /signup_events endpoint.

POST /signup_events

Example request

curl -v https://api.crewsense.com/v1/signup_events/5 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d '{ "admin_id": 848, "title": "My Signup Event", \ 
           "work_type_id": 123, "work_subtype_id": 222, \
           "start": "2019-01-01 08:00:00", "end": "2018-01-02 08:00:00", \ 
           "description": "First shift in New Year", "employees_needed": 10 }'

Example response (Event created successfully)

{
    "success": true,
    "code": 201,
    "status": "created",
    "message": "Added signup event My Signup Event",
    "id": 7
}

Create a new Signup Event in the system that employees can sign up for. The newly created event will have a status active, which means it’s immediately available for signup.

Parameters

Name Description Type Required?
admin_id The user ID of the admin creating the Signup Event. integer Y
title A descriptive name for the Signup Event. string Y
start Event start datetime Y
end Event end datetime Y
employees_needed The number of employees required to sign up before the event is closed. integer Y
work_type_id The ID of the work type used for signed up employees. integer Y
work_subtype_id The ID of the subtype of the work type (if any) integer N
description Longer description of the Signup Event in HTML string N

PUT /signup_events/{id}

Example request

curl -v https://api.crewsense.com/v1/signup_events/5 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -X PUT
     -d '{ "admin_id": 848, "title": "My Changed Signup Event", \ 
           "work_type_id": 123, "work_subtype_id": 222, \
           "start": "2019-01-01 08:30:00", "end": "2018-01-02 08:00:00", \ 
           "description": "First shift in New Year", "employees_needed": 10 }'

Example response (Event updated successfully)

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "Updated signup event My Changed Signup Event",
    "id": 7
}

Update a Signup Event. This is a PUT request that requires all fields to be sent in again. This way you can GET a Signup Event, make some modifications, and PUT the entire document to apply changes.

Parameters

See POST /signup_events parameters.

GET /signup_events/{id}/users

Example request

curl -v https://api.crewsense.com/v1/signup_events/5/users \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr"

Example response

[
    {
        "id": 2,
        "user": {
            "id": 138,
            "name": "Olivér Nagy",
            "href": "https://api.crewsense.com/v1/users/138"
        },
        "misc_hour_id": 12969
    },
    {
        "id": 3,
        "user": {
            "id": 848,
            "name": "Boss Doe",
            "href": "https://api.crewsense.com/v1/users/848"
        },
        "misc_hour_id": 12970
    }
]

Lists the users signed up for the Event.

Parameters

Name Description Type
id Unique identifier of the Signup Event User record. integer
user User who signed up for the Event. User
misc_hour_id The ID of the Misc. hours entry that was created when the user signed up. integer

POST /signup_events/{id}/users

Example request

curl -v https://api.crewsense.com/v1/signup_events/5/users \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d '{ "user_id": 848 }'

Example response

{
    "success": true,
    "code": 201,
    "status": "created",
    "message": "Signed Hass Brycen up for event My Changed Signup Event",
    "id": 7
}

Example response if user is already signed up

{
    "error": "invalid_params",
    "status": 422,
    "error_message": [
        "User #848 is already signed up for event #5"
    ]
}

Sign a user up for an event. A Misc. hour entry will automatically be created for the Signup Event duration with the selected work type / subtype.

DELETE /signup_events/{id}/users/{user_id}

Example request

curl -v https://api.crewsense.com/v1/signup_events/5/users/848 \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -X DELETE

Example response

{
    "success": true,
    "code": 200,
    "status": "ok",
    "message": "Removed Hass Brycen from event My Changed Signup Event",
    "id": 8
}

Example response if user is not signed up

{
    "error": "invalid_params",
    "status": 422,
    "error_message": [
        "User #848 not found in Signup Event."
    ]
}

Remove a user from a Signup Event. The auto-created Misc. hour entry will also be removed.

Availability

GET /availability_periods

GET /availability_periods sample response:

[   
    {
        "id": 47348,
        "user": {
            "id": 98,
            "name": "Boss Doe",
            "href": "https://api.crewsense.com/v1/users/98"
        },
        "start": "2017-09-04 08:00:00",
        "end": "2017-09-05 08:00:00",
        "admin": {
            "id": 34940,
            "name": "Oliver Nagy",
            "href": "https://api.crewsense.com/v1/users/34940"
        },
        "notes": "Travelling out of country",
        "unavailability_reason": {
            "id": 6,
            "name": "Default"
        }
    }
]

GET /availability_periods

Query Parameters

Field Description Required?
start date / time to return availability periods from y
end date / time to return availability periods to y

POST /availability_periods

POST /availability_periods sample JSON body:

{
    "user_id": 98,
    "start": "2017-11-17 08:00:00",
    "end": "2017-11-30 08:00:00",
    "unavailability_reason_id": 6,
    "admin_id": 98,
    "notes": "Added via the API"
}

POST /availability_periods

Query Parameters

Field Description Required?
user_id The ID of the user that is (un)available y
start date / time to return availability periods from y
end date / time to return availability periods to y
unavailability_reason_id The ID of the unavailability reason (if any) n
admin_id The User ID of the admin adding the period. If omitted, it will appear as if the user added the period themselves n
notes Notes about the period n

Announcements

GET /announcements

GET /announcements

{
   "data": [
        {
            "id": 238,
            "company_id": 8,
            "title": "Test",
            "body": "<p>This is a great HTML <strong>message!</strong></p>",
            "first_name": "Boss",
            "last_name": "Doe",
            "user": {
                "id": 848,
                "name": "Boss Doe",
                "href": "https://api.crewsense.com/v1/users/848"
            }
        },
        ...
    ],
    "pagination": {
        "prev": null,
        "next": null
    }
}

GET /announcements

Retrieve the latest, non-deleted announcements.

POST /announcements

POST /announcements

Create a new company announcement.

Query Parameters

Field Description Required?
body The text of the announcement, in HTML. Required
title Announcement title

PUT /announcements/{id}

Update a company announcement identified by id.

PUT /announcements/{id}

Field Description Required?
body The text of the announcement, in HTML. Required
title Announcement title

DELETE /announcements/{id}

DELETE /announcements/{id}

Delete the announcement by the id id.

Qualifiers

GET /qualifiers

GET /qualifiers

[
   {
      "id": 7,
      "name": "Captain",
      "shortcode": "CPT",
      "color": "#d81b60",
      "text_color": "#FFFFFF",
      "modified_by": null,
      "modified_on": null
   },
   {
      "id": 8,
      "name": "Firefighter",
      "shortcode": "FF",
      "color": "#d81b60",
      "text_color": "#FFFFFF",
      "modified_by": null,
      "modified_on": null
   }
]

GET /qualifiers

Retrieve all active CrewSense intelligence qualifiers in your system.

GET /qualifiers/{id}

GET /qualifiers/{id}

{
   "id": 8,
   "name": "Firefighter",
   "shortcode": "FF-01",
   "color": "#d81b60",
   "text_color": "#FFFFFF",
   "title_id": 23,
   "created_by": 848,
   "created_on": "2015-11-18 05:19:27",
   "modified_by": null,
   "modified_on": null,
   "deleted_at": null,
   "deleted_by": null
}

GET /qualifiers/{id}

Retreive all information about a specific qualifer by id.

POST /qualifers

POST /qualifiers

Create a new qualifier.

POST /qualifiers example response:

{
   "inserted": 1
}

Query Parameters

Field Description Required?
name Descriptive name of the qualifier Y
shortcode Shortened name of the qualifier, to be displayed on the Crew Scheduler

DELETE /qualifiers/{id}

DELETE /qualifiers/{id}

Delete a qualifier. The qualifier will be soft-deleted, which means we can manually restore it if you think you’ve made a mistake deleting it.

GET /qualifiers/{id}/users

GET /qualifiers/{id}/users

[
   {
      "id": 98,
      "name": "Hass Brycen",
      "ranking": 0
   },
   {
      "id": 138,
      "name": "Oliver Nagy",
      "ranking": 0
   },
   ...
]

GET /qualifiers/{id}/users

Retrieve all associated users of a specific qualifier.

Payroll

GET /payroll

Example request

curl -v https://api.crewsense.com/v1/payroll -G \
     -H "Authorization: Bearer CKRskOAU2tqYItxqlGnTt0VwXm4L0QABIvYrTBPr" \
     -d "start=2016-08-13 08:00:00" \
     -d "end=2016-08-14 08:00:00"

Example response

[
  {
    "type": "work shift",
    "user_id": "19218",
    "employee_id": "417",
    "name": "DAVID SMITH",
    "work_type": "Regular Time",
    "work_subtype": "Weekday",
    "work_code": "REG01",
    "start": "2016-08-13 08:00:00",
    "end": "2016-08-14 08:00:00",
    "assignment_id": 670,
    "assignment_name": "Engine 1",
    "labels": "CPT",
    "notes": "Worked as captain due to jones being sick",
    "total_hours": 24
  },
  ...
]

GET /payroll

Returns all payroll data for date range / time.

GET /payroll/{user_id}

Returns payroll data for the User in the given date range.

Query Parameters

Field Description Required?
start start date / time of payroll range Y
end end date / time of payroll range Y
user_id user id of employee N

Forms

GET /forms/

Example response

{
    "141": {
        "title": "Test form",
        "created_at": "2016-08-05 09:32:46",
        "created_by": "Brandon CrewSense"
    },
    "196": {
        "title": "Exposure Form",
        "created_at": "2016-08-06 16:49:33",
        "created_by": "Casey CrewSense"
    },
    "203": {
        "title": "Truck Check - Daily",
        "created_at": "2016-03-01 22:04:18",
        "created_by": "John Doe"
    }
}

GET /forms/

Lists all forms in the system

GET /forms/{id}/submissions

example GET /forms/144/submissions:

[
  {
    "user": {
      "id": "953",
      "name": "Casey McIntosh",
      "href": "https://api.crewsense.com/v1/users/953"
    },
    "submitted_at": "2015-09-23T19:27:28-0700",
    "submission": [
      {
        "title": "Date of Exposure",
        "value": "9/23/2015"
      },
      {
        "title": "Type of Exposure",
        "value": "Chemical"
      },
      {
        "title": "PPE Worn",
        "values": [
          "Gloves",
          "Eye Protection"
        ]
      },
      {
        "title": "Location of Exposure",
        "value": "Haz-Co"
      },
      {
        "title": "Employee Name",
        "value": "Joe Smith"
      },
      {
        "title": "Description of Exposure",
        "value": "While working in splash area; bleach was sprayed into the face of employee. No medical attention was required and standard cleanup processes were followed."
      },
      {
        "title": "Witnesse(s)",
        "value": "Jeff Davis"
      },...
]

GET /forms/{id}/submissions

Returns submitted form data for a specific form

ReadyAlert

POST /ready_alerts

POST /ready_alerts example JSON

{
   "type": "all",
   "ids": null,
   "body": "2nd alarm fire in town. Please respond ASAP!",
   "user_id": "124",
   "email": 0
}

POST /ready_alerts

Send ReadyAlert

Query Parameters

Field Description Required?
type (all, title, group, classification, user) Y
ids ids of type, array Y unless ALL is used
body the body of the message Y
user_id user id of employee sending ReadyAlert Y
email (boolean) send email as well?

Company

GET /company

GET /company

Returns company information

Bulletin Board

GET /bulletin_board

GET /bulletin_board example JSON

{
    "content": "<h1>Hey there!!!</h1><p>Please read the bulletin board</p>",
    "last_updated_by": {
        "id": 848,
        "name": "Boss Doe",
        "href": "https://api.crewsense.com/v1/users/848"
    },
    "last_updated_at": "2018-02-27T19:04:29+01:00"
}

GET /bulletin_board

Get the currently active Bulletin Board data. HTML is sanitized on the input side, it should be safe to output the content without further filtering.

PUT /bulletin_board

PUT /bulletin_board example request body

{
    "admin_id": 848,
    "content": "<h1>Hey there!!!</h1><p>Please read the UPDATED bulletin board</p>"
}

PUT /bulletin_board

Replaces the existing bulletin board entry with the one you send in the content parameter. Note that if the Bulletin Board is opened for editing in the web app, you’ll get a 409 Conflict response. In that case you should GET the resource again, implement your changes on the updated data, and send the PUT request again.

Query Parameters

Field Description Required?
admin_id User ID of the admin updating the Bulletin Board Y
content HTML of the Bulletin Board content. Some HTML is allowed. Y