Read

Get Assignments for all assignable people in a Company

GET - /v2/companies/<company_id>/assignments

Note: This is a pageable endpoint

Required Params

Property	Data Type	Description
startDay	ISO 8601 date string	The starting day to filter your assignment query on. *Note this will be evaluated to the timezone offset specified in the string.
page	Number	This is a 0-based index representing the page slice of the data you want to pull back.
dayRange	Number	A value specifying how many days forward you would like to get assignments for from the specified startDay. Assignments whose start_day falls within the given range will be returned in the response. Max value is 365

The startDay param in conjunction with the dayRange param will create a range of dates that will filter each assignment based on its start_day field.

For example, passing in a startDay of 2024-01-01 and a dayRange of 1 will return all assignments that begin on either the 1st or 2nd of January.

If we pass in the same startDay, but with a dayRange of 15, the results will include all assignments whose start_day exists between the dates of 2024-01-01 and 2024-01-15

Optional Query Params

The following query params accept ISO 8601 date strings, and are supported for every Assignment endpoint.

• created_at
• created_before (inclusive of the date passed in)
• created_after (inclusive of the date passed in)
• updated_at
• updated_before (inclusive of the date passed in)
• updated_after (inclusive of the date passed in)

The before/after params around created_at and updated_at fields can be used in conjunction with each other.

Ex. Find all assignments that were created sometime between January 1st and January 15th of 2024:

/v2/companies/_\<company_id>_/assignments?created_after=2024-01-01&created_before=2024-01-15

Responses:

Successful Response

When you get a successful response, you will be returned an object that contains the following properties possible_pages, current_page, data, and potentially warning.

The possible_pages property indicates the number of pages available to page through to get all of the data per your query params scope with the current_page property indicating the 0-based index of the page you just got the data for.

The data property is an array of objects representing people with any of their valid assignments and time off records contained within the date range specified by your query params. The data array will never be more than 100 people long per page of the query and is sorted alphanumerically by the person's full name.

Should you specify a page query param in your request that is out of bounds with the possible_pages, you will get back the warning property in the response with a message explaining why the data array is empty to prevent confusion if your paging incrementing gets away from you.

Everything in the returned data is pretty self-explanatory but we will note here that the work_days property in assignments indicate the active state of each week day (Sunday:0 - Saturday:6) with a true/false value.

Example Response

{
   "possible_pages": 3,
   "current_page": 0,
   "data": [
      {
         "person_id": "ce7da5a6-c908-4506-a251-16fcbf5e96d7",
         "person_name": "Aaron Kelly",
         "employee_number": "123-a234s-456",
         "job_title_name": "Apprentice-4",
         "job_title_id": "abe0afa9-c5be-4cee-8805-1adc88880d09",
         "job_title_color": "#5bd043",
         "assignments": [
            {
               "assignment_status": {
                  "abbreviation": "COMP",
                  "color": "#FFFB23",
                  "id": "c80148f1-1f29-4595-b552-08fbf16fdb30",
                  "name": "Complete"
               },
               "start_day": "6/25/18",
               "end_day": "6/29/18",
               "project_name": "Airport Concourse",
               "project_number": "112233",
               "project_id": "446e7813-02f0-4629-b2b7-81dd942a8941",
               "category_name": null,
               "category_id": null,
               "subcategory_name": null,
               "subcategory_id": null,
               "start_time": "7:30 AM",
               "end_time": "3:30 PM",
               "work_days": {
                  0: false,
                  1: true,
                  2: true,
                  3: true,
                  4: true,
                  5: true,
                  6: false
               },
               "id": "6bf79bbe-2038-423f-8fee-f890abcbd929",
               "created_at": "6/24/18",
               "updated_at": null
            },
            {
               "assignment_state": null,
               "start_day": "7/02/18",
               "end_day": "7/06/18",
               "project_name": "Purple Line Expansion",
               "project_number": "987654321",
               "project_id": "6288f5f8-8419-4b02-aaa9-846e57c51ba1",
               "category_name": "Phase 2",
               "category_id": "8a57a460-2b05-481f-99bf-4772aa761492",
               "subcategory_name": "North Lot",
               "subcategory_id": "5f0b9e08-b791-4fe9-9078-6d3800b000e3",
               "start_time": "7:30 AM",
               "end_time": "3:30 PM",
               "work_days": {
                  0: false,
                  1: true,
                  2: true,
                  3: true,
                  4: true,
                  5: true,
                  6: false
               },
               "id": "c2866ae9-7d9e-4b9d-9aaa-b848c2ec10b7",
               "created_at": "6/30/18",
               "updated_at": "7/01/18"
            }
            ...
         ],
         "timeoff": [
            {
               "reason": "family",
               "is_paid": true,
               "repeat": "never",
               "start_time": "7:00 AM",
               "end_time": "3:30 PM",
               "start_day": "7/09/18",
               "end_day": "7/13/18"
            }
         ]
      }
      ...
   ]
}

Get All Current Assignments

GET - /v2/companies/<company_id>/assignments/current

Note: This is a pageable endpoint

Returns all assignments where one of the assigned days falls on today or the optional date passed in.

Optional Params

Property	Data Type	Description
date	ISO 8601 date string	The date you wish to return assignments for. If the assignment has a working day that falls on this date, it will be included in the response. Defaults to today's date
page	Number	This is a 0-based index representing the page slice of the data you want to pull back.

Example: /v2/companies/_\<company_id>_/assignments/current?date=2024-06-01

This will return all assignments that have a day on June 1st, 2024.

Responses:

This endpoint uses the same response behavior has the All Company assignments endpoint listed above.

Get Assignments for all assignable people in a single Group

GET - /v2/companies/<company_id>/groups/<group_id>/assignments

Note: This is a pageable endpoint

Required Params

Property	Data Type	Description
startDay	ISO 8601 date string	The starting day to filter your assignment query on. *Note this will be evaluated to the timezone offset specified in the string.
page	Number	This is a 0-based index representing the page slice of the data you want to pull back.
dayRange	Number	A value specifying how many days forward you would like to get assignments for from the specified startDay. Assignments whose start_day falls within the given range will be returned in the response. Max value is 365

The startDay param in conjunction with the dayRange param will create a range of dates that will filter each assignment based on its start_day field.

For example, passing in a startDay of 2024-01-01 and a dayRange of 1 will return all assignments that begin on either the 1st or 2nd of January.

If we pass in the same startDay, but with a dayRange of 15, the results will include all assignments whose start_day exists between the dates of 2024-01-01 and 2024-01-15

Responses:

Successful Response

Same as the above company wide endpoint, just with the data limited to the scope of the group_id you provided in this endpoints url.

Get Assignments for a single Project

GET - /v2/companies/<company_id>/projects/<project_id>/assignments

Required Params

Property	Data Type	Description
startDay	ISO 8601 date string	The starting day to filter your assignment query on. *Note this will be evaluated to the timezone offset specified in the string.
dayRange	Number	A value specifying how many days forward you would like to get assignments for from the specified startDay. Assignments whose start_day falls within the given range will be returned. Max value is 365

The startDay param in conjunction with the dayRange param will create a range of dates that will filter each assignment based on its start_day field.

For example, passing in a startDay of 2024-01-01 and a dayRange of 1 will return all assignments that begin on either the 1st or 2nd of January.

If we pass in the same startDay, but with a dayRange of 15, the results will include all assignments whose start_day exists between the dates of 2024-01-01 and 2024-01-15

Responses:

Successful Response

With a successful response, you will get back a JSON array of objects like the one below representing any assignment to the specified Project in the scope of the query params you defined.

JSON

[
   {
      "id": "1a52e827-3b4e-4dff-903d-a321b378eb6c",
      "created_at": "6/20/18",
      "end_day": "6/29/18",
      "end_time": "3:30 PM",
      "person_id": "f6470e8b-013d-4145-b1b0-df05bceddad5",
      "person_name": "Hunter Gray",
      "project_id": "c805906e-8fe2-45ee-8525-72f1b4b58e58",
      "start_day": "6/25/18",
      "start_time": "7:30 AM",
      "updated_at": null,
      "state": null,
      "work_days": {
         0: false,
         1: true,
         2: true,
         3: true,
         4: true,
         5: true,
         6: false
      },
      "project_name": "Children’s Mercy Hospital - Labor & Delivery Unit",
      "project_number": "8203824",
      "category_name": "Apprentice",
      "subcategory_name": "North Lot",
      "category_id": "0c29fe4a-c183-4bec-a509-f8b7c694804c",
      "subcategory_id": "f87cbeb6-84e0-428d-b231-139e8e7180f4"
   }
   ...
]

Get Assignments for a single Person

GET - /v2/companies/<company_id>/people/<person_id>/assignments

Required Params

Property	Data Type	Description
startDay	ISO 8601 date string	The starting day to filter your assignment query on. *Note this will be evaluated to the timezone offset specified in the string.
dayRange	Number	A value specifying how many days forward you would like to get assignments for from the specified startDay. Assignments whose start_day falls within the given range will be returned in the response. Max value is 365

The startDay param in conjunction with the dayRange param will create a range of dates that will filter each assignment based on its start_day field.

For example, passing in a startDay of 2024-01-01 and a dayRange of 1 will return all assignments that begin on either the 1st or 2nd of January.

If we pass in the same startDay, but with a dayRange of 15, the results will include all assignments whose start_day exists between the dates of 2024-01-01 and 2024-01-15

Responses:

Successful Response

With a successful response, you will get back a JSON array of objects like the one below representing any assignment for the specified Person in the scope of the query params you defined.

JSON

[
   {
      "id": "6bf79bbe-2038-423f-8fee-f890abcbd929",
      "created_at": "6/24/18",
      "category_name": null,
      "end_day": "6/29/18",
      "end_time": "3:30 PM",
      "job_number": "112233",
      "person_id": "ce7da5a6-c908-4506-a251-16fcbf5e96d7",
      "project_color": "#53A9FF",
      "project_id": "446e7813-02f0-4629-b2b7-81dd942a8941",
      "project_name": "Airport Concourse",
      "start_day": "6/25/18",
      "start_time": "7:30 AM",
      "updated_at": null,
      "state": {
      "abbreviation": "COMP",
         "color": "#FFFB23",
         "id": "c80148f1-1f29-4595-b552-08fbf16fdb30",
         "name": "Complete"
      },
      "subcategory_name": null,
      "work_days": {
         0: false,
         1: true,
         2: true,
         3: true,
         4: true,
         5: true,
         6: false
      },
      "category_id": null,
      "subcategory_id": null,
      "person_name": "Aaron Kelly"
   }
   ...
]