Update
Update Person
POST - /v2/companies/<company_id>/people/<person_id>
Valid Update Properties
All Properties outlined on the People - Create page are valid properties to send across the Person update endpoint except those listed below for which there are additional convenience routes. It is only necessary to send key/val pairs for properties that are being updated. No need to send values for properties that aren't being changed.
Properties with special endpoints:
Updating Phone & Email
Just like when creating new People, when updating a Person's phone or email record both values must be unique within your company.
Updating group_ids
Group IDs can not be empty for an assignable resource or a non-admin person.
Updating to is_user = true
When performing an update on a Person who was previously only an assignable resource (
is_assignable = true) to now allow them to log into the application, please note that they will be required to have a validpermission_level_idvalue in the incoming update data.Also be aware that this type of update will trigger an email notification to the Person allowing them to set a password and receive access to their LaborChart account.
Responses:
Successful Response
Returns full JSON object of the updated Person.
{
"address_1": "1510 Walnut St" ,
"address_2": null ,
"can_recieve_email": true ,
"can_recieve_sms": false ,
"city_town": "Kansas City" ,
"company_id": "c2c32240-311b-4993-8263-243aa8ba000e" ,
"country": "United States" ,
"created_at": 1510867116807 ,
"dob": 1422739115919 ,
"email": "[email protected]",
"emergency_contact_email": null ,
"emergency_contact_name": null ,
"emergency_contact_number": null ,
"emergency_contact_relation": null ,
"employee_number": "123-a234s-456" ,
"group_ids": [
"9662f64f-74f4-478b-87a1-67fcbf14e803" ,
"9be574ab-fbe3-4839-a3b4-2e4bccb617ab" ,
"77a23dd5-7576-42cb-ab80-db706cff434a"
] ,
"hired_date": 1493237915919 ,
"hourly_wage": 35 ,
"id": "174b9d85-c5d0-407f-83c6-fb0fb1375bd7" ,
"is_assignable": true ,
"is_male": false ,
"is_user": false ,
"name": {
"first": "Anna" ,
"last": "Richardson"
} ,
"permission": null ,
"phone": null ,
"job_title_id": "8cf15293-6e3f-4382-931a-9dd5c14bd289" ,
"state_province": "MO" ,
"status": "active" ,
"tag_instances": [
{
"id": "3b24a193-202c-40f2-9b10-9f798a0ac3f9" ,
"tag_id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6"
} ,
{
"expr_date": 1510877312906 ,
"id": "7fa519f1-0ca6-4c2d-868b-fc4c18ed7319" ,
"tag_id": "bdb6a817-d1cc-48ec-9371-91b87ad4324f"
}
] ,
"updated_at": 1509251600000,
"zipcode": "66213"
}
[304] Not Modified - No Changes Were Made
If you try to update a person record and no changes were made, you will get a 304 response with no body.
[400] Bad Request - Group IDs can not be empty for an assignable resource or a non-admin person.
If you try to update an assignable resource or a non-admin person and leave group_idsempty array you'll get a 400 error with the following JSON body.
{
"code": "BadRequest",
"message": "Group IDs can not be empty for an assignable resource or a non-admin person"
}
[409] Failed Response - Duplicate Phone or Email
If you try to create a new Person and include a phone or email value that already exist in your company, you will get a 409 error with the following JSON body.
{
"code": "Conflict",
"message": "{\"detailCode\":\"personEmailOrPhoneConflict\",\"details\":\"Email [email protected] in use by another person.\"}"
}
Enable Person to Log In
POST - /v2/companies/<company_id>/people/<person_id>/user
To enable a Person to log in after they have already been created, send a post request to this endpoint with the below body.
Required Properties
| Property | Data Type | Description |
|---|---|---|
| permission_level_id | String | UUID of the Permission Level that you want for the user's access. |
Conditionally Optional Properties
| Property | Data Type | Description |
|---|---|---|
| String | The email the Person will use to log in. If the Person already has a email in LaborChart this can be left out, if not this becomes required. | |
| password | String | The password that the Person will use to log in. If this is not provided, the Person will receive an email from LaborChart instructing them to setup a password. If it is provided, they will not receive an email. LaborChart passwords must be complex. They require at least 1 uppercase, 1 lowercase, 1 number and must be 8 characters or longer. |
| no_invite | Boolean | If you would like to setup the person to have all of their user properties but not yet receive a user invite to the platform, you can include this property with a true value. You can then allow an Admin to manually trigger the user's invitation via a invite button on the users profile in the platform. |
Responses:
Successful Response
When you have successfully enabled a Person to log in you will receive their ID back as confirmation.
{"id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6"}
Revoke Person's Ability to Log In
DELETE - /v2/companies/<company_id>/people/<person_id>/user
This endpoint will revoke a Person's ability to log in but leave them in as an assignable resource in the system.
Successful Response
When you have revoked a Person's ability to log in you will receive their ID back as confirmation.
{"id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6"}
Add Tag Instance to Person
POST - /v2/companies/<company_id>/people/<person_id>/tags
The POST body of this request will must contain a specified tag_id referencing the Tag you want to apply to this Person and optionally a expr_date value that is either a ISO Date String, UTC Date String or MS numeric representation of Epoch Time
{
"tag_id": "94186279-fa66-42c6-a2ca-f44dde84f584",
"expr_date": 1511228654337
}
Responses:
Successful Response
A successful addition of a Tag will return a UUID representing the newly added Tag Instances.
{"id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6"}
Tag ID vs Tag Instance ID
Something that can be a bit confusing is having both an
idandtag_idvalue in each Tag Instance object. The best way to keep it straight is theidproperty references specifically the applied instance of the Tag where as thetag_idactually references the Tag entity in your LaborChart system. The reason both must exist is so you can use the Tag Instance ID to remove applied tags from People as you will see with the endpoint below. This structure also allows for the flexibility of having two different instances of the same Tag on a single Person should you want to per the way your organization is using Tags.
Remove Tag Instance from Person
DELETE - /v2/companies/<company_id>/people/<person_id>/tags/<tag_instance_id>
Responses:
Successful Response
If the Tag Instance was successfully removed from the Person you will receive a response with the removed Tag Instance ID
{"id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6"}
Add Person to Group
POST - /v2/companies/<company_id>/people/<person_id>/groups
To grant a Person access to or to make them available to a new Group simply hit this endpoint with the group_id of the new Group in the POST body.
{"group_id": "3f447732-33ec-4b8e-a5d0-6462c12e18e6"}
Responses:
Successful Response
When a Person has successfully been associated to a new Group, all (including the new UUID) of their current Group IDs are returned so you can keep mappings up to date in your system if you desire.
{
"group_ids": [
"ea8fac53-e05f-49bc-a630-dd0c7739570b",
"aeee8fc5-b8ee-4bf0-bca9-86f751f99795",
"3f447732-33ec-4b8e-a5d0-6462c12e18e6"
]
}
Remove Person from Group
DELETE - /v2/companies/<company_id>/people/<person_id>/groups/<group_id>
Removing the last group_id
Group IDs can not be empty for an assignable resource or a non-admin person. Therefore, the removing the last group id from an assignable resource or a non-admin person is not allowed.
Responses:
Successful Response
When a Person has successfully been removed from a Group, all (without the removed UUID) of their current Group IDs are returned so you can keep mappings up to date in your system if you desire.
{
"group_ids": [
"ea8fac53-e05f-49bc-a630-dd0c7739570b",
"aeee8fc5-b8ee-4bf0-bca9-86f751f99795"
]
}
Updated 5 months ago