{"swagger":"2.0","info":{"title":"Service API","version":"v1"},"host":"","schemes":["http","https"],"produces":["application/vnd.api+json","application/json"],"consumes":["application/vnd.api+json","application/json"],"paths":{"/api/v1/authenticate":{"post":{"summary":"Create a JSON Web Token for authentication","tags":["Authentication"],"parameters":[{"name":"credentials","in":"body","schema":{"type":"object","properties":{"company_name":{"type":"string"},"username":{"type":"string"},"key":{"type":"string"}},"required":["company_name","username","key"],"example":{"company_name":"Westeros_1571077143","username":"robert","key":"g1YQnGeBLBw029q0seb2cWSTH4OkKYH7"}}}],"responses":{"401":{"description":"Incorrect API credentials","examples":{"application/json":{"errors":[{"status":"401","title":"Incorrect API credentials"}]}}},"404":{"description":"Cannot find either company_name or username","examples":{"application/json":{"errors":[{"status":"404","title":"Cannot find either company_name or username"}]}}},"200":{"description":"Successfully authenticated","examples":{"application/json":{"message":"Successfully authenticated","data":{"token":"Token <token here>"}}}}}}},"/api/v1/authenticated":{"get":{"summary":"Check authentication","tags":["Authentication"],"security":[{"Token":[]}],"responses":{"200":{"description":"Successfully authenticated","examples":{"application/json":{"message":"Successfully authenticated"}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}}},"/api/v1/group_types/{id}":{"get":{"summary":"Find group type by ID","tags":["Group Types"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"integer","required":true}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","items":{"properties":{"self":{"type":"string"}}}},"data":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"404":{"description":"Group type not found","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}},"patch":{"summary":"Update group type","tags":["Group Types"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"string","required":true},{"name":"body","in":"body","required":true,"schema":{"type":"object","properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","example":"group_types"},"id":{"type":"string","example":"1"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"Location"}}}}}}}}],"responses":{"200":{"description":"group type updated"},"404":{"description":"group type not found","examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}}}},"delete":{"summary":"Delete group type","tags":["Group Types"],"description":"Before deleting a group type, you must delete the groups associated with that group type.","security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"string","required":true}],"responses":{"204":{"description":"group type deleted"},"404":{"description":"organization not found","examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}}}}},"/api/v1/group_types":{"get":{"summary":"List group types","tags":["Group Types"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"filter[name]","in":"query","type":"string","required":false,"description":"Case-sensitive"},{"name":"sort","in":"query","type":"string","required":false,"description":"Sort fields must be given in lowercase. Valid sort fields include: name and created_at"},{"name":"page[number]","in":"query","type":"integer","required":false,"default":1},{"name":"page[size]","in":"query","type":"integer","required":false,"default":100,"description":"Must be less than or equal to 100"}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","items":{"properties":{"self":{"type":"string"}}}},"data":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"created_at":{"type":"string"}}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"400":{"description":"Bad Request","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}},"post":{"summary":"Create group type","tags":["Group Types"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"body","in":"body","required":true,"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"group_types"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"Location"}}}}}}}}],"responses":{"201":{"description":"group type successfully created"}}}},"/api/v1/groups/{id}":{"get":{"summary":"Find group by ID","tags":["Groups"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"integer","required":true}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","items":{"properties":{"self":{"type":"string"}}}},"data":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"group_type_id":{"type":"integer"},"created_at":{"type":"string"}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"404":{"description":"Group not found","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}},"patch":{"summary":"Update group","tags":["Groups"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"string","required":true},{"name":"body","in":"body","required":true,"schema":{"type":"object","properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","example":"groups"},"id":{"type":"string","example":"1"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"Engineers"},"group_type_id":{"type":"string","example":"23","description":"corresponds to the id of the group type for the given group"}}}}}}}}],"responses":{"200":{"description":"group updated"},"404":{"description":"group not found","examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}}}},"delete":{"summary":"Delete group","tags":["Groups"],"description":"Before deleting a group, you must disassociate any users belonging to that group.","security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"string","required":true}],"responses":{"204":{"description":"group deleted"},"404":{"description":"organization not found","examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}}}}},"/api/v1/groups":{"get":{"summary":"List groups","tags":["Groups"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"filter[name]","in":"query","type":"string","required":false,"description":"Case-sensitive"},{"name":"sort","in":"query","type":"string","required":false,"description":"Sort fields must be given in lowercase. Valid sort fields include: name and created_at"},{"name":"page[number]","in":"query","type":"integer","required":false,"default":1},{"name":"page[size]","in":"query","type":"integer","required":false,"default":100,"description":"Must be less than or equal to 100"}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","items":{"properties":{"self":{"type":"string"}}}},"data":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"name":{"type":"string"},"group_type_id":{"type":"integer"},"created_at":{"type":"string"}}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"400":{"description":"Bad Request","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}},"post":{"summary":"Create group","tags":["Groups"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"body","in":"body","required":true,"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"groups"},"attributes":{"type":"object","properties":{"name":{"type":"string","example":"Engineers"},"group_type_id":{"type":"string","example":"23","description":"corresponds to the id of the group type for the given group"}}}}}}}}],"responses":{"201":{"description":"group successfully created"}}}},"/api/v1/currencies/{id}":{"get":{"summary":"Find currency by ID","tags":["Currencies"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"integer","required":true}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","properties":{"self":{"type":"string"}}},"data":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"precision":{"type":"integer"},"id":{"type":"string"}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"404":{"description":"Currency not found","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}}},"/api/v1/measurements":{"get":{"summary":"List measurements","tags":["Measurements"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"page[number]","in":"query","type":"integer","required":false,"default":1},{"name":"page[size]","in":"query","type":"integer","required":false,"default":100,"description":"Must be less than or equal to 100"}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"start_date":{"type":"string"},"due_date":{"type":"string"},"completed_date":{"type":"string"},"percent_complete":{"type":"integer"},"status":{"type":"string"},"id":{"type":"string"}}},"relationships":{"type":"object","properties":{}}}}},"links":{"type":"object","properties":{"self":{"type":"string"},"meta":{"type":"object","properties":{"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total_items":{"type":"integer"},"total_pages":{"type":"integer"}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}}},"/api/v1/measurements/{id}":{"get":{"summary":"Find measurement by ID","tags":["Measurements"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"integer","required":true}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","properties":{"self":{"type":"string"}}},"data":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"title":{"type":"string"},"description":{"type":"string"},"start_date":{"type":"string"},"due_date":{"type":"string"},"completed_date":{"type":"string"},"percent_complete":{"type":"integer"},"status":{"type":"string"},"id":{"type":"string"}}},"relationships":{"type":"object","properties":{}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"404":{"description":"Measurement not found","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}}},"/api/v1/currencies":{"get":{"summary":"List currencies","tags":["Currencies"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"page[number]","in":"query","type":"integer","required":false,"default":1},{"name":"page[size]","in":"query","type":"integer","required":false,"default":100,"description":"Must be less than or equal to 100"}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string"},"code":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"precision":{"type":"integer"}}}}}},"links":{"type":"object","properties":{"self":{"type":"string"},"meta":{"type":"object","properties":{"page_number":{"type":"integer"},"page_size":{"type":"integer"},"total_items":{"type":"integer"},"total_pages":{"type":"integer"}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}}},"/api/v1/reviews/{id}":{"get":{"summary":"Find review by ID","tags":["Reviews"],"description":"Get an archived review by ID","security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"integer","required":true}],"responses":{"404":{"description":"User not found","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}}},"/api/v1/reviews":{"get":{"summary":"List reviews","tags":["Reviews"],"description":"List all archived reviews for all active users in your organization","security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"filter[manager_score_numeric_min]","in":"query","type":"string","required":false,"description":"Manager score above this value"},{"name":"filter[manager_score_numeric_max]","in":"query","type":"string","required":false,"description":"Manager score below this value"},{"name":"filter[employee_score_numeric_min]","in":"query","type":"string","required":false,"description":"Employee score above this value"},{"name":"filter[employee_score_numeric_max]","in":"query","type":"string","required":false,"description":"Employee score below this value"},{"name":"filter[average_360_rater_score_numeric_min]","in":"query","type":"string","required":false,"description":"Average 360-Rater score above this value"},{"name":"filter[average_360_rater_score_numeric_max]","in":"query","type":"string","required":false,"description":"Average 360-Rater score below this value"},{"name":"filter[completed_on_min]","in":"query","type":"string","required":false,"description":"Archive date after this value"},{"name":"filter[completed_on_max]","in":"query","type":"string","required":false,"description":"Archive date before this value"},{"name":"filter[manager_id]","in":"query","type":"string","required":false,"description":"Manager ID matching this value"},{"name":"filter[employee_id]","in":"query","type":"string","required":false,"description":"Employee ID matching this value"},{"name":"page[number]","in":"query","type":"integer","required":false,"default":1},{"name":"page[size]","in":"query","type":"integer","required":false,"default":100,"description":"Must be less than or equal to 100"},{"name":"sort","in":"query","type":"string","required":false,"description":"\n          Sorts the returned reviews. Reverse the order by prepending a hyphen to the parameter, e.g.\n          sort=manager_score_numeric\n          sort=-manager_score_numeric\n\n          - manager_score_numeric - Numeric manager score\n          - employee_score_numeric - Numeric employee score\n          - average_360_rater_score_numeric - Numeric average 360-Rater score\n          - manager_id - Manager ID\n          - employee_id - Employee ID\n        "}],"responses":{"200":{"description":"Lists Reviews","schema":{"type":"object","properties":{"links":{"type":"object","items":{"properties":{"self":{"type":"string"}}}},"data":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"},"properties":{"type":"object","properties":{"review_title":{"type":"string"},"manager_score_formatted":{"type":"string"},"manager_score_numeric":{"type":"string"},"employee_score_formatted":{"type":"string"},"employee_score_numeric":{"type":"string"},"average_360_rater_score_formatted":{"type":"string"},"average_360_rater_score_numeric":{"type":"string"},"completed_on":{"type":"string"},"manager_id":{"type":"string"},"employee_id":{"type":"string"}}},"relationships":{"type":"object","properties":{"manager":{"type":"object","properties":{"links":{"type":"object","properties":{"related":{"type":"string"}}},"data":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}}}}},"employee":{"type":"object","properties":{"links":{"type":"object","properties":{"related":{"type":"string"}}},"data":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"}}}}}}}}}},"included":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"},"properties":{"type":"object","properties":{"first_last":{"type":"string"}}}}}}}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}}},"/api/v1/users/{id}":{"get":{"summary":"Find user by ID","tags":["Users"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"integer","required":true},{"name":"include","in":"query","type":"string","required":false,"description":"value can be 'groups' to include user group information in results"}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","items":{"properties":{"self":{"type":"string"}}}},"data":{"type":"object","properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"employee_number":{"type":"string"},"username":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"hire_date":{"type":"string"},"base_date":{"type":"string"},"current_login_at":{"type":"string"},"must_reset_password":{"type":"boolean"},"welcome_email_sent_at":{"type":"string"},"terminated":{"type":"boolean"},"roles":{"type":"array","items":{}},"manager_user_id":{"type":"integer"},"form_name":{"type":"string"},"process_name":{"type":"string"},"review_archive_date":{"type":"string"},"locale_format":{"type":"string"},"locale_lang":{"type":"string"}}},"relationships":{"type":"object","properties":{"groups":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"}}}},"links":{"type":"object","properties":{"self":{"type":"string"}}}}}}}}},"included":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"404":{"description":"User not found","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}},"400":{"description":"Bad Request","examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}},"patch":{"summary":"Update user","tags":["Users"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"string","required":true},{"name":"include","in":"query","type":"string","required":false,"description":"value can be 'groups' to include user group information in results"},{"name":"body","in":"body","required":true,"schema":{"type":"object","properties":{"data":{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","example":"users"},"id":{"type":"string","example":"5"},"attributes":{"type":"object","properties":{"first_name":{"type":"string","example":"Jane"},"last_name":{"type":"string","example":"Doe"},"employee_number":{"type":"string","example":"employee123","description":"employee_number must be present and unique amongst all employees within your organization."},"username":{"type":"string","example":"username1","description":"username must be present and unique amongst all employees within your organization."},"email":{"type":"string","example":"my_email@example.com","description":"email must be present if organization has Mitratech HQ integration enabled."},"hire_date":{"type":"string","example":"2019-09-29","description":"Please use the format YYYY-MM-DD when providing dates."},"base_date":{"type":"string","example":"2019-09-29","description":"The base date for this user's review set. Please use the format YYYY-MM-DD when providing dates."},"password":{"type":"string","example":"MyPassword!"},"must_reset_password":{"type":"boolean","example":true,"description":"If this option is set to true, the user will be required to change their password on the next login regardless of whether or not you're also passing along a password."},"form_name":{"type":"string","example":"Manager in training"},"unrecognized_form_name_action":{"type":"string","description":"Optional attribute to be included to specify what action to take if the provided 'form_name' is not found.  This can be either 'blank', or 'copy'.  'blank' will create a new, empty form with the 'form_name' provided.  'copy' will require the 'form_name_for_copy' attribute to be provided and a valid existing from to use as the basis for a copy while using the 'form_name' attribute for the copied forms new name.","example":"copy"},"form_name_for_copy":{"type":"string","description":"When the 'unrecognized_form_name_action' attribute is provided and set to 'copy', this field will specify the existing form to lookup and copy while using the 'form_name' attribute as the new form's name.","example":"Older form to Copy"},"process_name":{"type":"string","example":"Annual"},"manager_user_id":{"type":"string","example":"64","description":"This is the user id of the person who will be assigned as the manager.  This can be found by searching via our index routes and referencing the `id` field that gets returned.  NOTE: this person must have the manager role in order to be assigned."},"review_archive_date":{"type":"string","example":"2020-03-31","description":"Primary Review Set Archive by date."},"terminated":{"type":"boolean","example":true,"description":"If this option is included, setting the value to true will preform any other requested updates to the user and then mark them as terminated.  If the option is set to false, the system will attempt to revive a user from the terminated state to being active and then preform any other requested updates.  NOTE: if you're not trying to terminate or revive a user, please leave out this option."},"termination_date":{"type":"string","example":"2019-09-29","description":"This option is only necessary and useful when including the terminated attribute and setting it to true.  The results from that will mark the user as terminated and set their termination date to the one provided instead of defaulting to today's date."},"group_ids":{"type":"array","example":["1","2","3"],"description":"A list of any / all group ids a user should belong to.  NOTE: when updating a user, any ids that a user is currently associated with that is not included in this list will remove the user from those groups."},"group_names":{"type":"array","example":[{"group_type_name":"Location","group_name":"Dragonstone"}],"description":"A list of group names a user should belong to.  NOTE: when updating a user, any groups that a user is currently associated with that is not included in this list will remove the user from those groups."},"roles":{"type":"array","example":["admin","manager"],"description":"A list of any / all roles that can be attributed to a user.  All users have the role of \"employee\" by default and that role cannot be stripped.  NOTE: when updating a user, any roles that a user is currently associated with that is not included in this list will be removed."},"locale_format":{"type":"string","example":"en_GB","description":"The user's format locale. Accepted values: 'auto' (resets to default), 'en', 'en_GB', 'en_CA', 'en_AU'."},"locale_lang":{"type":"string","example":"fr_CA","description":"The user's language locale. Accepted values: 'auto' (resets to default), 'en', 'fr_CA'."}}}}}}}}],"description":"\n        Update a user's attributes.\n\n        Setting the \"terminated\" field to \"true\" will mark this user as terminated, preventing them from logging into the application.\n\n        This action can be undone by setting the \"terminated\" field to \"false\".\n\n        Terminating a user will cancel any active reviews. Archived reviews will not be affected. \n\n        Users who are assigned as managers cannot be terminated, please reassign their direct reports first.\n\n        Users who are assigned as managers and have direct reports cannot have their manager role removed, please reassign their direct reports first.\n        \n        Users with API keys will have their keys invalidated when terminated.\n      ","responses":{"200":{"description":"user updated"},"400":{"description":"missing required attributes","examples":{"application/json":{"errors":[{"status":"400","title":"Missing Required Attributes","detail":"attributes for update must also include: employee_number, username"}]}}},"404":{"description":"user not found","examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}}}},"delete":{"summary":"Delete user","tags":["Users"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"string","required":true},{"name":"body","in":"body","schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"users"},"id":{"type":"string","example":"46"},"attributes":{"type":"object","properties":{"termination_date":{"type":"string","example":"2019-09-24","description":"The use of termination date for permanently deleting a user is solely for logging purposes."}}}}}}}}],"description":"\n        Permanently deleting a user will remove them from the application and cannot be undone.\n\n        If you wish to terminate a user without removing them from the application, see the Update user endpoint.\n\n        Users who are assigned as managers cannot be deleted, please reassign their direct reports first. \n\n        Active reviews for this user will be canceled. Archived reviews will not be affected. \n\n        Users with API keys will have their keys invalidated.\n      ","responses":{"204":{"description":"user deleted"},"404":{"description":"user not found","examples":{"application/json":{"errors":[{"status":"404","title":"Resource not found"}]}}}}}},"/api/v1/users":{"get":{"summary":"List users","tags":["Users"],"security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"filter[email]","in":"query","type":"string","required":false,"description":"Case-sensitive"},{"name":"filter[employee_number]","in":"query","type":"string","required":false,"description":"Case-sensitive. Since employee_number is unique across all users, only one user will be returned."},{"name":"filter[first_name]","in":"query","type":"string","required":false,"description":"Case-sensitive e.g. searching for 'Jon' is NOT the same as searching for 'jon'."},{"name":"filter[last_name]","in":"query","type":"string","required":false,"description":"Case-sensitive e.g. searching for 'Snow' is NOT the same as searching for 'snow'."},{"name":"filter[manager_user_id]","in":"query","type":"integer","required":false,"description":"The user ID of their manager"},{"name":"filter[must_reset_password]","in":"query","type":"boolean","required":false},{"name":"filter[form_name]","in":"query","type":"string","required":false,"description":"Case-sensitive. The name of their Form in the organization."},{"name":"filter[process_name]","in":"query","type":"string","required":false,"description":"Case-sensitive. The name of the process associated with their primary review."},{"name":"filter[roles]","in":"query","type":"string","required":false,"description":"The roles the user has in the software e.g. admin, restricted_admin, manager"},{"name":"filter[terminated]","in":"query","type":"boolean","required":false,"description":"By default, terminated users will not be included. To select terminated users only, set this to true."},{"name":"filter[username]","in":"query","type":"string","required":false,"description":"Case-sensitive. Since username is unique across all users, only one user may be returned."},{"name":"filter[current_login_at_min]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"filter[current_login_at_max]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"filter[hire_date_min]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"filter[hire_date_max]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"filter[review_archive_date_min]","in":"query","type":"string","required":false,"description":"The due date of their primary review. Format is YYYY-MM-DD."},{"name":"filter[review_archive_date_max]","in":"query","type":"string","required":false,"description":"The due date of their primary review. Format is YYYY-MM-DD."},{"name":"filter[terminated_date_min]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"filter[terminated_date_max]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"filter[welcome_email_sent_at_min]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"filter[welcome_email_sent_at_max]","in":"query","type":"string","required":false,"description":"Format is YYYY-MM-DD"},{"name":"sort","in":"query","type":"string","required":false,"description":"Sort fields must be given in lowercase. Valid sort fields include: id, employee_number, username, first_name, last_name, email, hire_date, current_login_at, must_reset_password, welcome_email_sent_at, terminated, terminated_date, manager_user_id, form_name, process_name, review_archive_date, and roles"},{"name":"include","in":"query","type":"string","required":false,"description":"value can be 'groups' to include user group information in results"},{"name":"page[number]","in":"query","type":"integer","required":false,"default":1},{"name":"page[size]","in":"query","type":"integer","required":false,"default":100,"description":"Must be less than or equal to 100"}],"responses":{"200":{"description":"Success","schema":{"type":"object","properties":{"links":{"type":"object","items":{"properties":{"self":{"type":"string"}}}},"data":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"employee_number":{"type":"string"},"username":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"hire_date":{"type":"string"},"base_date":{"type":"string"},"current_login_at":{"type":"string"},"must_reset_password":{"type":"boolean"},"welcome_email_sent_at":{"type":"string"},"terminated":{"type":"boolean"},"terminated_date":{"type":"string"},"roles":{"type":"array","items":{}},"manager_user_id":{"type":"integer"},"form_name":{"type":"string"},"process_name":{"type":"string"},"review_archive_date":{"type":"string"},"locale_format":{"type":"string"},"locale_lang":{"type":"string"}}},"relationships":{"type":"object","properties":{"groups":{"type":"object","properties":{"data":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"}}}},"links":{"type":"object","properties":{"self":{"type":"string"}}}}}}}}}},"included":{"type":"array","items":{"properties":{"type":{"type":"string"},"id":{"type":"string"},"attributes":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}}}},"jsonapi":{"type":"object","properties":{"version":{"type":"string"}}}}}},"400":{"description":"Bad Request","schema":{"type":"object","properties":{"errors":{"type":"array","items":{"properties":{"status":{"type":"string"},"title":{"type":"string"},"detail":{"type":"string"}}}}}},"examples":{"application/json":{"errors":[{"status":"400","title":"Bad Request"}]}}},"401":{"description":"Invalid token","examples":{"application/json":{"errors":[{"status":"401","title":"Invalid token"}]}}}}},"post":{"summary":"Create user","tags":["Users"],"description":"\n        Create a user by specifying personal and review related attributes.\n\n        When specifying review details (form, process, manager, and archive date), a corresponding Review Set and Review will be created.\n\n        If review details are not supplied, no Review will exist for this user and their ability to interact with the system will be limited.\n      ","security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"include","in":"query","type":"string","required":false,"description":"value can be 'groups' to include user group information in results"},{"name":"body","in":"body","required":true,"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"type":{"type":"string","example":"users"},"attributes":{"type":"object","properties":{"first_name":{"type":"string","example":"Jane","description":"first_name must be present"},"last_name":{"type":"string","example":"Doe","description":"last_name must be present"},"employee_number":{"type":"string","example":"employee123","description":"employee_number must be present and unique amongst all employees within your organization."},"username":{"type":"string","example":"username1","description":"username must be present and unique amongst all employees within your organization."},"email":{"type":"string","example":"my_email@example.com","description":"email must be present if organization has Mitratech HQ integration enabled."},"hire_date":{"type":"string","example":"2019-09-29","description":"Please use the format YYYY-MM-DD when providing dates."},"base_date":{"type":"string","example":"2019-09-29","description":"The base date for this user's review set. Please use the format YYYY-MM-DD when providing dates."},"password":{"type":"string","example":"MyPassword!"},"must_reset_password":{"type":"boolean","description":"If this option is set to true, the user will be required to change their password on the next login regardless of whether or not you're also passing along a password."},"form_name":{"type":"string","example":"Manager in training"},"unrecognized_form_name_action":{"type":"string","description":"Optional attribute to be included to specify what action to take if the provided 'form_name' is not found.  This can be either 'blank', or 'copy'.  'blank' will create a new, empty form with the 'form_name' provided.  'copy' will require the 'form_name_for_copy' attribute to be provided and a valid existing from to use as the basis for a copy while using the 'form_name' attribute for the copied forms new name.","example":"copy"},"form_name_for_copy":{"type":"string","description":"When the 'unrecognized_form_name_action' attribute is provided and set to 'copy', this field will specify the existing form to lookup and copy while using the 'form_name' attribute as the new form's name.","example":"Older form to Copy"},"process_name":{"type":"string","example":"Annual"},"manager_user_id":{"type":"string","example":"64","description":"This is the user id of the person who will be assigned as the manager.  This can be found by searching via our index routes and referencing the `id` field that gets returned.  NOTE: this person must have the manager role in order to be assigned."},"review_archive_date":{"type":"string","example":"2020-03-31","description":"Primary Review Set Archive by date."},"group_ids":{"type":"array","example":["1","2","3"],"description":"A list of any / all group ids a user should belong to."},"group_names":{"type":"array","example":[{"group_type_name":"Location","group_name":"Dragonstone"}],"description":"A list of group names a user should belong to."},"roles":{"type":"array","example":["admin","manager"],"description":"Additional roles that a user can assume."},"locale_format":{"type":"string","example":"en_GB","description":"The user's format locale. Accepted values: 'auto' (resets to default), 'en', 'en_GB', 'en_CA', 'en_AU'."},"locale_lang":{"type":"string","example":"fr_CA","description":"The user's language locale. Accepted values: 'auto' (resets to default), 'en', 'fr_CA'."}}}}}}}}],"responses":{"201":{"description":"user successfully created"},"400":{"description":"missing required attributes","examples":{"application/json":{"errors":[{"status":"400","title":"Missing Required Attributes","detail":"attributes for create must also include: employee_number, username"}]}}}}}},"/api/v1/users/{id}/send_welcome_email":{"post":{"summary":"Send welcome email to user","tags":["Users"],"description":"Send an email detailing login instructions to the specified user. Note: the provided password is temporary and can only be used once. Upon logging in, the user will be required to set a new password.","security":[{"Token":[]}],"parameters":[{"name":"Content-Type","in":"header","type":"string","required":true,"default":"application/vnd.api+json"},{"name":"id","in":"path","type":"string","required":true},{"name":"data","in":"body","schema":{"type":"object","properties":{"type":{"type":"string","example":"users"},"id":{"type":"string","example":"46"}}}}],"responses":{"204":{"description":"welcome email sent"},"403":{"description":"Access Denied - trying to send a welcome email to a user who is ineligible to receive such an email, such as a terminated user.","examples":{"application/json":{"errors":[{"status":"403","title":"Forbidden"}]}}}}}}},"securityDefinitions":{"Token":{"type":"apiKey","name":"Authorization","description":"Enter the following \"Token \\<your token\\>\"","in":"header"}}}