Create

Create Single Project

POST - /v2/companies/<company_id>/projects

Required Properties

Property	Data Type	Description
name	String	Project's Name
status	String	Valid Options: active, pending, inactive Controls Project visibility and filtering
group_ids	Array of String	UUID references to the Groups this project should be available to.

Required Properties if status = 'active'

Property	Data Type	Description
start_date	ISO Date String / UTC Date String / MS Numeric Representation of Epoch Time	Project's start date

Optional Properties

timezone	String	Ex: America/Chicago The timezone to use for things like scheduling outbound messages for the Project. If not supplied, the Group timezone will be used as a fallback. List of valid options here
color	String (Hex Val)	Ex: #53A9FF Color can be helpful as an additional categorical tool to signify something to the end user or help them quickly find a Project.
daily_start_time	String	Default: 7:30 am Time format needs to be structures as "HH:MM am/pm". Leading 0 on single digit hours is not needed. For minutes, only 15 minute increments are currently used by our scheduling system and thus all we allow here. If you provide something other than a 15 minute increment, it will be rounded.
daily_end_time	String	Default: 3:30 pm Time format needs to be structures as "HH:MM am/pm". Leading 0 on single digit hours is not needed. For minutes, only 15 minute increments are currently used by our scheduling system and thus all we allow here. If you provide something other than a 15 minute increment, it will be rounded.
start_date	ISO Date String / UTC Date String / MS Numeric Representation of Epoch Time	Project start date. May have already been specified per above conditional requirements.
est_end_date	ISO Date String / UTC Date String / MS Numeric Representation of Epoch Time	Estimated end date for the Project
closed_date	ISO Date String / UTC Date String / MS Numeric Representation of Epoch Time	If loading in already closed jobs for historical tracking purposes, you can populate this field.
address_1	String	The first part of the Project's Address
address_2	String	The second part of the Project's Address
city_town	String	The City/Town for the Project
state_province	String	The State/Province for the Project
zipcode	String	Zip/Postal Code for the Project
country	String	Country for the Project
project_number	String	Your own Project identifier
bid_rate	Number	Project bid rate
percent_complete	Number	The percentage of the Project that is complete
customer_name	String	Customer's name
project_type	String	Any categorical classifier you use internally to label your Projects
tag_instances	Array of Object	See Tag Instances section below
categories	Array of Object	See Categories/Subcategories section below
wage_overrides	Array of Object	See Wage Overrides section below
roles	Array of Object	See Roles section below

Tag Instances

In your LaborChart System you can set up Tags to act as categorical labels or expiring certifications. Applying them to Projects can be helpful to both add categorical labelling to the Project as well as identifying what Tags the People being assigned to the Project need.

📘

Tags on Projects

It should be noted that unlike on People, Tags do not expire on Projects even if the Tag is set up to be an expiring Tag. The reason for this is that expiring tags are usually a certification associated with the assigned resources and are intended to represent requirements when applied to Projects vs. representing actual instances of certifications as they do when applied to People.

To add a Tag to the initial creation data for a Project you simply need to include an object like the one below in the tag_instances array per Tag you would like to apply. In these Tag Instance objects, the tag_id will reference the UUID for the Tag you are referencing.

Ex:

Tag Instances Ex.

{
  "tag_instances": [
    {
      "tag_id": "2d2ad78e-c6de-467e-8413-c616b55294a5"
    },
    {
      "tag_id": "94186279-fa66-42c6-a2ca-f44dde84f584"
    }
  ]
}

Categories / Subcategories

Inside Projects, Categories define buckets to assign resources to. Inside Categories exist Subcategories which act as a nested layer of classification for your assignments. Every Project is created with a default "None" Category so you can make assignments to the Project without adding any Category or Subcategory specification. The "None" Category cannot be removed but you do have the facility to add as many additional custom Categories and Subcategories to Projects as you want.

📘

Sequenced Categories

In the LaborChart app, users can drag and drop the order of Categories in the Project detail page so that they appear on the assignments views in the order they would like them. For this reason, when creating a Project with Categories, the order of the Categories in the categories array will dictate their starting sequence within the app. Although your end users can change this down the road, if you care about the sequence, it should be factored into your integration.

To add custom Categories and Subcategories to a Project upon creation, mirror the below data structure for the categories property.

Categories Ex.

"categories": [
  {
    "name": "Phase 1",
    "subcategories": [
      {name: "North Lot"},
      {name: "South Lot"}
    ]
  },
  {
    "name": "Night Shift",
    "subcategories": [
      {name: "Jake's Crew"},
      {name: "Clean Up"}
    ]
  },  
  {
    "name": "Finishing",
    "subcategories": []
  },  
  {
    "name": "Pre-Con"
  }
]

Wage Overrides

When setting up a Project in LaborChart, you can configure Wage Overrides to provide a prevailing hourly rate for any assignments on that Project with resources of specific Job Titles. Even if the Person on the assignment has a hourly rate configured, the Wage Override will take precedence when doing daily rate and daily burn calculations on the Project. Due to the logical context of Wage Overrides, you can only have 1 Wage Override per Job Title per project so that the resulting calculations happen in a predictable manner.

To add Wage Overrides to a Project upon creation, follow the below data structure for the wage_overrides property. The job_title_id needs to reference the UUID of the specific Job Title you are trying to override hourly rates for.

Wage Overrides Ex.

"wage_overrides": [
  {
    "job_title_id": "bc107873-b2fe-4f8f-9879-6d95b4a0684f",
    "rate": 45
  },
  {
    "job_title_id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6",
    "rate": 30
  }
]

Roles

LaborChart facilitates specifying certain People to various Roles on a Project. This functions both as a way to quickly reference who is responsible for what on a Project but also connects with other features of the app to make things as seamless as possible for users. For example, When sending out assignment notifications for a Project, users will have the option to select from any People assigned to Roles on that Project to CC them on the assignment notification as a heads up or even dynamically pull in their contact information into the notification content.

As you can see, there are a lot of benefits to defining Roles for your Project. Each Role specification contains a Person's UUID and Job Title UUID. Some companies find that they like to create additional Job Titles to only be used as Project Roles and override their People's actual Job Title with this Role specific Job Title when assigning them as a Role to a Project. A common example of this can be seen in Roles like "P.O.C" or "Client Relation" which are obviously not the Person's day to day Job Title.

📘

Using People's Default Job Titles

When specifying Roles via the API, if you leave out the job_title_id for a Role instance, our system will attempt to automatically look up the existing Job Title for the Person you have specified and use that. If the specified Person doesn't have a Job Title registered in our system, that Role instance will be considered invalid and not added to the Project.

To add Roles to your Project upon creation, follow the below data structure for the roles property

Roles Ex.

"roles": [
  {
    "person_id": "d7852dc1-f466-467b-8e64-4fa74ac16e4a",
    "job_title_id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6"
  },
  {
    "person_id": "bc107873-b2fe-4f8f-9879-6d95b4a0684f"
  }
]

Full POST Body Ex.

Full Project

{
  "address_1":  "1111 S Figueroa St" ,
  "address_2":  "Building 17" ,
  "bid_rate": 20 ,
  "city_town":  "Los Angeles" ,
  "closed_date": null ,
  "color":  "#53A9FF" ,
  "categories": [
    {
      "subcategories": [
        {
          "name":  "North Lot" 
        },
        {
          "name":  "South Lot" 
        }
      ] ,
      "name":  "Phase 1" ,
    } ,
    {
      "subcategories": [] ,
      "name":  "Finishing" ,
    } ,
  ] ,
  "country":  "United States" ,
  "customer_name": "City of Los Angeles" ,
  "daily_end_time": "3:30 pm" ,
  "daily_start_time": "7:30 am" ,
  "est_end_date": null ,
  "group_ids": [
    "9be574ab-fbe3-4839-a3b4-2e4bccb617ab" ,
    "2ec02e52-8a14-4689-adec-bbd6161e37a4"
  ] ,
  "project_number":  "1zx212ms" ,
  "name":  "Airport Concourse" ,
  "percent_complete": 30 ,
  "project_type": "Airport" ,
  "roles": [
    {
      "person_id":  "572a480a-637e-4d0e-a02e-246b0181562c" ,
      "job_title_id":  "38f2a244-365f-409e-8e94-60bbae1097a6"
    } ,
    {
      "person_id":  "56f96a61-b0d2-489e-981c-572da8cf9ba1" 
    }
  ] ,
  "start_date": 1509771600000 ,
  "state_province":  "KS" ,
  "status":  "active" ,
  "tag_instances": [
    {
      "tag_id":  "3f447732-33ec-4b8e-a5d0-6462c12e18e6"
    } ,
    {
      "tag_id":  "66cecf20-b095-4f65-a386-06bc25d34d94"
    }
  ] ,
  "timezone": "America/Los_Angeles" ,
  "wage_overrides": [
    {
      "job_title_id":  "38f2a244-365f-409e-8e94-60bbae1097a6" ,
      "rate": 35
    } ,
    {
      "job_title_id":  "e70d45dd-27dc-43ad-ab1a-abd4c54bbe3a" ,
      "rate": 122
    }
  ] ,
  "zipcode":  "66085"
}

Responses:

Successful Response

When a Project is successfully created, you will be returned the new Project UUID.

{"id": "2d2ad78e-c6de-467e-8413-c616b55294a5"}