> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/api-reference-app/organization-or-employees.md).

# Organization | Employees

## GET /v1/organization/employees

> Retrieve a list of employees of your organization tenant.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"EmployeeStatus":{"enum":["onboarding","active","leave","offboarding","inactive"],"type":"string","description":"Status of an employee"},"EmployeeSortParameter":{"enum":["mail","firstName","lastName","workplace"],"type":"string","description":"Parameters according to which an employee can be sorted."},"SortOrder":{"enum":["asc","desc"],"type":"string","description":"Order in which the result of a list request is sorted."},"EmployeeList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Employee"},"description":"The list of result items."},"total":{"type":"integer","description":"The total number of items.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"Employee":{"required":["id","self","username"],"type":"object","properties":{"employer":{"$ref":"#/components/schemas/CompanyReference"},"workplace":{"$ref":"#/components/schemas/LocationReference"},"supervisor":{"$ref":"#/components/schemas/EmployeeReference"},"employeeNumber":{"maxLength":50,"minLength":0,"type":"string","description":"Employee number in the company. Usually created by the HR system/process.","nullable":true},"position":{"maxLength":150,"minLength":0,"type":"string","description":"The job position or job title of the employee","nullable":true},"privateEmail":{"maxLength":100,"minLength":0,"type":"string","description":"The private email address.","nullable":true},"phoneBusiness":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees workplace.","nullable":true},"phoneMobile":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees business mobile phone.","nullable":true},"notes":{"maxLength":1000,"minLength":0,"type":"string","description":"Free text notes.","nullable":true},"created":{"type":"string","description":"The date and time the data record was created.","format":"date-time"},"onboardingDate":{"type":"string","description":"The employee onboarding date.","format":"date-time","nullable":true},"offboardingDate":{"type":"string","description":"The employee offboarding date.","format":"date-time","nullable":true},"status":{"$ref":"#/components/schemas/EmployeeStatus"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"},"description":"The groups the employee belongs to (departments, teams etc.)","nullable":true},"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"CompanyReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the company in the system.","format":"int64"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"Group":{"required":["id","name","self"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/GroupType"},"category":{"type":"string","description":"A customizable category of the group. Can be used to categorize groups independent from the group type.","nullable":true},"companyName":{"maxLength":100,"minLength":0,"type":"string","description":"A customizable company name of the group. Can be used to distinguish same departments between different sub companies of the tenant.","nullable":true},"description":{"type":"string","description":"The description of the group.","nullable":true},"email":{"type":"string","description":"The email address of the group.","nullable":true},"manager":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeReference"},"description":"A list of employee references assigned as managers for a group.","nullable":true},"tags":{"type":"array","items":{"type":"string"},"description":"Assigned tags","nullable":true},"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"GroupType":{"enum":["custom","company","department","project","team"],"type":"string","description":"Type of the group."},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees":{"get":{"tags":["Organization | Employees"],"summary":"Retrieve a list of employees of your organization tenant.","parameters":[{"name":"locations","in":"query","description":"Filter by one or multiple specific locations","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"statuses","in":"query","description":"Filter the employees by one or multiple statuses","schema":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeStatus"}}},{"name":"usernames","in":"query","description":"Filter the employees by one or multiple usernames","schema":{"type":"array","items":{"type":"string"}}},{"name":"createdAfter","in":"query","description":"Filter the employees created after the specified date.","schema":{"type":"string","format":"date-time"}},{"name":"sortBy","in":"query","description":"Sort the items by a given criterion.","schema":{"$ref":"#/components/schemas/EmployeeSortParameter"}},{"name":"sortOrder","in":"query","description":"Sort the items in a given order (asc|desc).","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"offset","in":"query","description":"Specifies the index of the first item to return","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"Specifies the maximum number of items to return (min: 1; max: 1000)","schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"OK: Returns a list of employees.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeList"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Create an employee.

> When an employee is created, an instance of the "Employee Account" system service is also always added to the approval cart. \
> \
> A new employee is always in the \`\`\`onboarding\`\`\` status. To update the status please order and process the system service "Employee Account".\
> \
> An employee can only be deleted as long as the "Employee Account" is not ordered nor processed.\
> \
> Note: the field username is unique troughout the whole system. Therefore duplicates are not allowed and will result in a \`\`\`409 Conflict\`\`\`.

````json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"EmployeeCreateModel":{"required":["email","firstName","lastName","locationId","username"],"type":"object","properties":{"employeeNumber":{"maxLength":50,"minLength":0,"type":"string","description":"Employee number in the company. Usually created by the HR system/process.","nullable":true},"onboardingDate":{"type":"string","description":"The employee onboarding date.","format":"date-time","nullable":true},"offboardingDate":{"type":"string","description":"The employee offboarding date.","format":"date-time","nullable":true},"invitation":{"$ref":"#/components/schemas/InvitationModel"},"roles":{"type":"array","items":{"$ref":"#/components/schemas/UserRole"},"description":"Specifies the roles assigned to the employee for logging in to Equipme. Default is \"user\".","nullable":true},"email":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The contact mail address."},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee."},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee."},"locationId":{"maximum":2147483647,"minimum":1,"type":"integer","description":"The identifier of the location where the employee works.","format":"int32"},"notes":{"maxLength":1000,"minLength":0,"type":"string","description":"Free text notes.","nullable":true},"phoneMobile":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees business mobile phone.","nullable":true},"phonePrimary":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees workplace.","nullable":true},"position":{"maxLength":150,"minLength":0,"type":"string","description":"The job position or job title of the employee","nullable":true},"status":{"$ref":"#/components/schemas/EmployeeStatus"},"supervisorId":{"type":"integer","description":"The identifier of an employee who is the supervisor for this employee.","format":"int32","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"selfServiceEnabled":{"type":"boolean","description":"Controls whether the employee can access the self-service portal."}},"additionalProperties":false},"InvitationModel":{"type":"object","properties":{"loginMethod":{"$ref":"#/components/schemas/LoginMethod"},"message":{"maxLength":1000,"minLength":0,"type":"string","description":"Additional message which will displayed in the invitation mail below the regular information. Can be used to give the employee further information.","nullable":true}},"additionalProperties":false,"description":"Configures the invitation to be sent to the employee."},"LoginMethod":{"enum":["password","sso"],"type":"string"},"UserRole":{"enum":["administrator","planner","user"],"type":"string","description":"Roles available to be assigned to an employee as a user in Equipme. Options will be extended in the future."},"EmployeeStatus":{"enum":["onboarding","active","leave","offboarding","inactive"],"type":"string","description":"Status of an employee"},"Employee":{"required":["id","self","username"],"type":"object","properties":{"employer":{"$ref":"#/components/schemas/CompanyReference"},"workplace":{"$ref":"#/components/schemas/LocationReference"},"supervisor":{"$ref":"#/components/schemas/EmployeeReference"},"employeeNumber":{"maxLength":50,"minLength":0,"type":"string","description":"Employee number in the company. Usually created by the HR system/process.","nullable":true},"position":{"maxLength":150,"minLength":0,"type":"string","description":"The job position or job title of the employee","nullable":true},"privateEmail":{"maxLength":100,"minLength":0,"type":"string","description":"The private email address.","nullable":true},"phoneBusiness":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees workplace.","nullable":true},"phoneMobile":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees business mobile phone.","nullable":true},"notes":{"maxLength":1000,"minLength":0,"type":"string","description":"Free text notes.","nullable":true},"created":{"type":"string","description":"The date and time the data record was created.","format":"date-time"},"onboardingDate":{"type":"string","description":"The employee onboarding date.","format":"date-time","nullable":true},"offboardingDate":{"type":"string","description":"The employee offboarding date.","format":"date-time","nullable":true},"status":{"$ref":"#/components/schemas/EmployeeStatus"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"},"description":"The groups the employee belongs to (departments, teams etc.)","nullable":true},"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"CompanyReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the company in the system.","format":"int64"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"Group":{"required":["id","name","self"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/GroupType"},"category":{"type":"string","description":"A customizable category of the group. Can be used to categorize groups independent from the group type.","nullable":true},"companyName":{"maxLength":100,"minLength":0,"type":"string","description":"A customizable company name of the group. Can be used to distinguish same departments between different sub companies of the tenant.","nullable":true},"description":{"type":"string","description":"The description of the group.","nullable":true},"email":{"type":"string","description":"The email address of the group.","nullable":true},"manager":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeReference"},"description":"A list of employee references assigned as managers for a group.","nullable":true},"tags":{"type":"array","items":{"type":"string"},"description":"Assigned tags","nullable":true},"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"GroupType":{"enum":["custom","company","department","project","team"],"type":"string","description":"Type of the group."},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees":{"post":{"tags":["Organization | Employees"],"summary":"Create an employee.","description":"When an employee is created, an instance of the \"Employee Account\" system service is also always added to the approval cart. \n\nA new employee is always in the ```onboarding``` status. To update the status please order and process the system service \"Employee Account\".\n\nAn employee can only be deleted as long as the \"Employee Account\" is not ordered nor processed.\n\nNote: the field username is unique troughout the whole system. Therefore duplicates are not allowed and will result in a ```409 Conflict```.","requestBody":{"description":"The employee to be created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeCreateModel"}}}},"responses":{"201":{"description":"Created: The created employee.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
````

## GET /v1/organization/employees/{employeeId}

> Retrieve a single employee by its id.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"Employee":{"required":["id","self","username"],"type":"object","properties":{"employer":{"$ref":"#/components/schemas/CompanyReference"},"workplace":{"$ref":"#/components/schemas/LocationReference"},"supervisor":{"$ref":"#/components/schemas/EmployeeReference"},"employeeNumber":{"maxLength":50,"minLength":0,"type":"string","description":"Employee number in the company. Usually created by the HR system/process.","nullable":true},"position":{"maxLength":150,"minLength":0,"type":"string","description":"The job position or job title of the employee","nullable":true},"privateEmail":{"maxLength":100,"minLength":0,"type":"string","description":"The private email address.","nullable":true},"phoneBusiness":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees workplace.","nullable":true},"phoneMobile":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees business mobile phone.","nullable":true},"notes":{"maxLength":1000,"minLength":0,"type":"string","description":"Free text notes.","nullable":true},"created":{"type":"string","description":"The date and time the data record was created.","format":"date-time"},"onboardingDate":{"type":"string","description":"The employee onboarding date.","format":"date-time","nullable":true},"offboardingDate":{"type":"string","description":"The employee offboarding date.","format":"date-time","nullable":true},"status":{"$ref":"#/components/schemas/EmployeeStatus"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/Group"},"description":"The groups the employee belongs to (departments, teams etc.)","nullable":true},"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"CompanyReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the company in the system.","format":"int64"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeStatus":{"enum":["onboarding","active","leave","offboarding","inactive"],"type":"string","description":"Status of an employee"},"Group":{"required":["id","name","self"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/GroupType"},"category":{"type":"string","description":"A customizable category of the group. Can be used to categorize groups independent from the group type.","nullable":true},"companyName":{"maxLength":100,"minLength":0,"type":"string","description":"A customizable company name of the group. Can be used to distinguish same departments between different sub companies of the tenant.","nullable":true},"description":{"type":"string","description":"The description of the group.","nullable":true},"email":{"type":"string","description":"The email address of the group.","nullable":true},"manager":{"type":"array","items":{"$ref":"#/components/schemas/EmployeeReference"},"description":"A list of employee references assigned as managers for a group.","nullable":true},"tags":{"type":"array","items":{"type":"string"},"description":"Assigned tags","nullable":true},"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"GroupType":{"enum":["custom","company","department","project","team"],"type":"string","description":"Type of the group."},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees/{employeeId}":{"get":{"tags":["Organization | Employees"],"summary":"Retrieve a single employee by its id.","parameters":[{"name":"employeeId","in":"path","description":"The identifier of the employee.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK: The requested employee.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Employee"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## Update an existing employee.

> Overwrites all existing data with that from the request body.\
> \
> To remove an assignment of the employee (e.g. supervisor), transfer the respective value as \`\`\`null\`\`\` value.

````json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"EmployeeUpdateModel":{"required":["email","firstName","lastName","locationId","username"],"type":"object","properties":{"email":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The contact mail address."},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee."},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee."},"locationId":{"maximum":2147483647,"minimum":1,"type":"integer","description":"The identifier of the location where the employee works.","format":"int32"},"notes":{"maxLength":1000,"minLength":0,"type":"string","description":"Free text notes.","nullable":true},"phoneMobile":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees business mobile phone.","nullable":true},"phonePrimary":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees workplace.","nullable":true},"position":{"maxLength":150,"minLength":0,"type":"string","description":"The job position or job title of the employee","nullable":true},"status":{"$ref":"#/components/schemas/EmployeeStatus"},"supervisorId":{"type":"integer","description":"The identifier of an employee who is the supervisor for this employee.","format":"int32","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"selfServiceEnabled":{"type":"boolean","description":"Controls whether the employee can access the self-service portal."}},"additionalProperties":false},"EmployeeStatus":{"enum":["onboarding","active","leave","offboarding","inactive"],"type":"string","description":"Status of an employee"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees/{employeeId}":{"put":{"tags":["Organization | Employees"],"summary":"Update an existing employee.","description":"Overwrites all existing data with that from the request body.\n\nTo remove an assignment of the employee (e.g. supervisor), transfer the respective value as ```null``` value.","parameters":[{"name":"employeeId","in":"path","description":"The identifier of the employee to be updated.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"updateInstancesCostCenter","in":"query","description":"If true, the cost center of all instances will be update in case the cost center from employee has changed","schema":{"type":"boolean","default":true}}],"requestBody":{"description":"The data to process the updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmployeeUpdateModel"}}}},"responses":{"204":{"description":"NoContent: Request has succeeded."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
````

## POST /v1/organization/employees/{employeeId}/invitations

> Sends an invitation for the app portal to the employee

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"InvitationModel":{"type":"object","properties":{"loginMethod":{"$ref":"#/components/schemas/LoginMethod"},"message":{"maxLength":1000,"minLength":0,"type":"string","description":"Additional message which will displayed in the invitation mail below the regular information. Can be used to give the employee further information.","nullable":true}},"additionalProperties":false,"description":"Configures the invitation to be sent to the employee."},"LoginMethod":{"enum":["password","sso"],"type":"string"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees/{employeeId}/invitations":{"post":{"tags":["Organization | Employees"],"summary":"Sends an invitation for the app portal to the employee","parameters":[{"name":"employeeId","in":"path","description":"The identifier of the employee to be invited.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The data to process the invitation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InvitationModel"}}}},"responses":{"204":{"description":"NoContent: Request has succeeded."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /v1/organization/employees/{employeeId}/metadata

> Get all metadata items for an employee

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"MetadataList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/MetadataItem"},"description":"The list of result items."},"total":{"type":"integer","description":"The total number of items.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"MetadataItem":{"required":["key","self"],"type":"object","properties":{"value":{"maxLength":500,"minLength":0,"type":"string","description":"Metadata value","nullable":true},"scope":{"type":"string","description":"Metadata scope. Can be Customer or Supplier to indicate the metadata is specific to a customer or supplier.","nullable":true},"key":{"maxLength":150,"minLength":0,"type":"string","description":"Metadata key used as a unique identifier for the metadata item."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees/{employeeId}/metadata":{"get":{"tags":["Organization | Employees"],"summary":"Get all metadata items for an employee","parameters":[{"name":"employeeId","in":"path","description":"","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataList"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found."}}}}}}
```

## POST /v1/organization/employees/{employeeId}/metadata

> Create a metadata item for an employee.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"MetadataItemCreateModel":{"type":"object","properties":{"key":{"maxLength":150,"type":"string","description":"Key for the new metadata entry","nullable":true},"value":{"maxLength":500,"type":"string","description":"Metadata value","nullable":true}},"additionalProperties":false,"description":"DTO for creating a new metadata entry for a given resource which implements the logic"},"MetadataItem":{"required":["key","self"],"type":"object","properties":{"value":{"maxLength":500,"minLength":0,"type":"string","description":"Metadata value","nullable":true},"scope":{"type":"string","description":"Metadata scope. Can be Customer or Supplier to indicate the metadata is specific to a customer or supplier.","nullable":true},"key":{"maxLength":150,"minLength":0,"type":"string","description":"Metadata key used as a unique identifier for the metadata item."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees/{employeeId}/metadata":{"post":{"tags":["Organization | Employees"],"summary":"Create a metadata item for an employee.","parameters":[{"name":"employeeId","in":"path","description":"The unique employee identifier","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The metadata item model","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataItemCreateModel"}}}},"responses":{"201":{"description":"Created: The created metadata entry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataItem"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found."}}}}}}
```

## GET /v1/organization/employees/{employeeId}/metadata/{key}

> Get a specific metadata item for an employee

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"MetadataItem":{"required":["key","self"],"type":"object","properties":{"value":{"maxLength":500,"minLength":0,"type":"string","description":"Metadata value","nullable":true},"scope":{"type":"string","description":"Metadata scope. Can be Customer or Supplier to indicate the metadata is specific to a customer or supplier.","nullable":true},"key":{"maxLength":150,"minLength":0,"type":"string","description":"Metadata key used as a unique identifier for the metadata item."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees/{employeeId}/metadata/{key}":{"get":{"tags":["Organization | Employees"],"summary":"Get a specific metadata item for an employee","parameters":[{"name":"employeeId","in":"path","description":"Employee unique id","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"key","in":"path","description":"metadata key","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ok","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataItem"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found."}}}}}}
```

## DELETE /v1/organization/employees/{employeeId}/metadata/{key}

> Delete a specific metadata item for an employee

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Employees"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/employees/{employeeId}/metadata/{key}":{"delete":{"tags":["Organization | Employees"],"summary":"Delete a specific metadata item for an employee","parameters":[{"name":"employeeId","in":"path","description":"The unique employee id","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"key","in":"path","description":"The metadata key","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"NoContent"},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found."}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://hub.equipme.io/development/api-reference-app/organization-or-employees.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.