> 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-groups.md).

# Organization | Groups

## GET /v1/organization/groups

> Retrieve a list of groups of your organization tenant.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"GroupType":{"enum":["custom","company","department","project","team"],"type":"string","description":"Type of the group."},"GroupSortParameter":{"enum":["name"],"type":"string","description":"Parameters according to which groups can be sorted."},"SortOrder":{"enum":["asc","desc"],"type":"string","description":"Order in which the result of a list request is sorted."},"GroupList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Group"},"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},"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},"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},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/groups":{"get":{"tags":["Organization | Groups"],"summary":"Retrieve a list of groups of your organization tenant.","parameters":[{"name":"types","in":"query","description":"Filter by one or multiple specific group types","schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupType"}}},{"name":"categories","in":"query","description":"Filter by one or multiple specific group categories","schema":{"type":"array","items":{"type":"string"}}},{"name":"companyNames","in":"query","description":"Filter by one or multiple company names related to the group","schema":{"type":"array","items":{"type":"string"}}},{"name":"sortBy","in":"query","description":"Sort the items by a given criterion.","schema":{"$ref":"#/components/schemas/GroupSortParameter"}},{"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: The requested groups.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupList"}}}},"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 customer could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## POST /v1/organization/groups

> Create a group.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"GroupCreate":{"required":["name","type"],"type":"object","properties":{"type":{"$ref":"#/components/schemas/GroupType"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the group."},"category":{"maxLength":50,"minLength":0,"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":{"maxLength":500,"minLength":0,"type":"string","description":"The description of the group.","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 email of the group.","nullable":true}},"additionalProperties":false},"GroupType":{"enum":["custom","company","department","project","team"],"type":"string","description":"Type of the group."},"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},"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},"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/groups":{"post":{"tags":["Organization | Groups"],"summary":"Create a group.","requestBody":{"description":"The group to be created for the customer.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupCreate"}}}},"responses":{"201":{"description":"Created: The created group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"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/groups/{groupId}

> Retrieve a single group by its id.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"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."},"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},"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/groups/{groupId}":{"get":{"tags":["Organization | Groups"],"summary":"Retrieve a single group by its id.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK: The requested group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Group"}}}},"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 group.

> Overwrites all existing data with that from the request body.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"GroupUpdate":{"required":["name"],"type":"object","properties":{"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the group."},"category":{"maxLength":50,"minLength":0,"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":{"maxLength":500,"minLength":0,"type":"string","description":"The description of the group.","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 email of the group.","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/groups/{groupId}":{"put":{"tags":["Organization | Groups"],"summary":"Update an existing group.","description":"Overwrites all existing data with that from the request body.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group to be updated.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The group data to process the update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupUpdate"}}}},"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"}}}}}}}}}
```

## DELETE /v1/organization/groups/{groupId}

> Delete a group.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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/groups/{groupId}":{"delete":{"tags":["Organization | Groups"],"summary":"Delete a group.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group to be deleted.","required":true,"schema":{"type":"integer","format":"int32"}}],"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/groups/{groupId}/members

> Retrieve the members of a group.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"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},"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/groups/{groupId}/members":{"get":{"tags":["Organization | Groups"],"summary":"Retrieve the members of a group.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group.","required":true,"schema":{"type":"integer","format":"int32"}},{"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: The requested group members.","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"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## POST /v1/organization/groups/{groupId}/members

> Add group members.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"GroupMemberReference":{"type":"object","properties":{"id":{"type":"integer","description":"The id of the group member.","format":"int32"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/groups/{groupId}/members":{"post":{"tags":["Organization | Groups"],"summary":"Add group members.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group to which new members are to be added.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The identifiers of the employees to be added.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupMemberReference"}}}}},"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"}}}}}}}}}
```

## DELETE /v1/organization/groups/{groupId}/members

> Delete group members.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"GroupMemberReference":{"type":"object","properties":{"id":{"type":"integer","description":"The id of the group member.","format":"int32"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/groups/{groupId}/members":{"delete":{"tags":["Organization | Groups"],"summary":"Delete group members.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group whose members are to be deleted.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The identifiers of the group members to be deleted.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupMemberReference"}}}}},"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/groups/{groupId}/metadata

> Get all metadata items for a given organizational-group

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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/groups/{groupId}/metadata":{"get":{"tags":["Organization | Groups"],"summary":"Get all metadata items for a given organizational-group","parameters":[{"name":"groupId","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/groups/{groupId}/metadata

> Create a metadata entry for a organizational-group

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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/groups/{groupId}/metadata":{"post":{"tags":["Organization | Groups"],"summary":"Create a metadata entry for a organizational-group","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group for which the metadata entry is to be created.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The metadata entry to be created.","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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```

## GET /v1/organization/groups/{groupId}/metadata/{key}

> Get a single metadata item of a given organizational-group

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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/groups/{groupId}/metadata/{key}":{"get":{"tags":["Organization | Groups"],"summary":"Get a single metadata item of a given organizational-group","parameters":[{"name":"groupId","in":"path","description":"The unique identifier for the target organization unit","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"key","in":"path","description":"The 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/groups/{groupId}/metadata/{key}

> Delete a single metadata item for a given organizational-group

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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/groups/{groupId}/metadata/{key}":{"delete":{"tags":["Organization | Groups"],"summary":"Delete a single metadata item for a given organizational-group","parameters":[{"name":"groupId","in":"path","description":"","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"key","in":"path","description":"","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"No Content"},"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/groups/{groupId}/service-instances

> Retrieve the service instances of a group.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"ServiceInstanceSortParameter":{"enum":["product","supplier","customer","oneTimeCosts","recurringCosts","activationDate","lastModified","expirationDate","inventoryNumber"],"type":"string"},"SortOrder":{"enum":["asc","desc"],"type":"string","description":"Order in which the result of a list request is sorted."},"ServiceInstanceList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceInstance"},"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},"ServiceInstance":{"required":["id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"activationDate":{"type":"string","description":"The date the service instance was activated.","format":"date-time","nullable":true},"lastModifiedDate":{"type":"string","description":"The date the service instance was last modified.","format":"date-time","nullable":true},"expirationDate":{"type":"string","description":"The date when the service instance should expire.","format":"date-time","nullable":true},"processStatus":{"type":"string","description":"The processing status of the service instance.","nullable":true},"active":{"type":"boolean","description":"True if the service instance is active, otherwise false."},"oneTimeCosts":{"type":"number","description":"One-time purchase costs of the instance in its life cycle to date.","format":"double"},"recurringCosts":{"type":"number","description":"The current recurring costs for the service instance. Only calculated for active instances.","format":"double"},"currencyCode":{"type":"string","description":"Currency in ISO 4217","nullable":true},"subscriptionPeriod":{"type":"integer","description":"The minimum subscription period (in months) for the services instance.","format":"int32","nullable":true},"subscriptionPeriodRenewal":{"type":"integer","description":"Number of months a subscription is renewed after its expiration time if it has not been terminated.","format":"int32","nullable":true},"note":{"type":"string","description":"A note on the service instance. Supports html formatted text including inline css styles.","nullable":true},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"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."},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"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},"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},"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/groups/{groupId}/service-instances":{"get":{"tags":["Organization | Groups"],"summary":"Retrieve the service instances of a group.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"services","in":"query","description":"Filter by one or multiple specific services of your portfolio","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"statuses","in":"query","description":"Filter by one or multiple specific statuses","schema":{"type":"array","items":{"type":"string"}}},{"name":"active","in":"query","description":"Filter the instances which are active or not active. When null, all instances will be returned. Default: null","schema":{"type":"boolean"}},{"name":"subscriptionPeriodRenewals","in":"query","description":"Filter by one or multiple specific values for the period renewal, e.g. to filter all without a renewal use 0","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"modifiedSince","in":"query","description":"Filter the instances modified after the specified date. A modification is\n            identified when: the assignment changed, the instance got activated, the instance got cancelled","schema":{"type":"string","format":"date-time"}},{"name":"expiresAfter","in":"query","description":"Filter the instances which expire after this date","schema":{"type":"string","format":"date-time"}},{"name":"expiresBefore","in":"query","description":"Filter the instances which expire before this date","schema":{"type":"string","format":"date-time"}},{"name":"search","in":"query","description":"Filter for id, service name, inventory number, employee first and last name, group, location name or metadata values","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort the items by a given criterion.","schema":{"$ref":"#/components/schemas/ServiceInstanceSortParameter"}},{"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: The requested service instances of a group.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstanceList"}}}},"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/groups/{groupId}/service-instances

> Add service instances to a group.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"GroupServiceInstanceReference":{"required":["id"],"type":"object","properties":{"id":{"maximum":2147483647,"minimum":1,"type":"integer","description":"The id of the service instance.","format":"int32"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/groups/{groupId}/service-instances":{"post":{"tags":["Organization | Groups"],"summary":"Add service instances to a group.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group to which new service instances are to be added.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The identifiers of the service instances to be added.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupServiceInstanceReference"}}}}},"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"}}}}}}}}}
```

## DELETE /v1/organization/groups/{groupId}/service-instances

> Delete service instances from a group.

```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Organization | Groups"}],"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":{"GroupServiceInstanceReference":{"required":["id"],"type":"object","properties":{"id":{"maximum":2147483647,"minimum":1,"type":"integer","description":"The id of the service instance.","format":"int32"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/organization/groups/{groupId}/service-instances":{"delete":{"tags":["Organization | Groups"],"summary":"Delete service instances from a group.","parameters":[{"name":"groupId","in":"path","description":"The identifier of the group from which the service instances are to be deleted.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The identifiers of the service instances to be deleted.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/GroupServiceInstanceReference"}}}}},"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"}}}}}}}}}
```


---

# 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-groups.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.