> For the complete documentation index, see [llms.txt](https://help.security.gallagher.com/knowledge-hub/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.security.gallagher.com/knowledge-hub/developer/rest-api/elevator-groups.md).
# Elevator Groups
These methods give you read access to Elevator Groups.
The reason you would want that is to allocate default floors to cardholders. Each cardholder can have one default floor per elevator group, so that when they badge into that group's lobby area the elevator system can arrange a car to take them to their favourite floor.
Each elevator group only goes to certain floors, so to give a cardholder a default floor you need to see which floors each elevator group services.
Command Centre represents floors with access zones. If an elevator car has two doors, front and rear, it may service two access zones on the same physical floor. A cardholder could pick either of those access zones as their default for that elevator group.
The main entry point is a paginated search that returns what you need to pick default floors for a cardholder, limited by the privilege that enables that operation on a cardholder. That is the call that you are most likely to need, but there is another that gives you all elevator groups that your operator can view, rather than the smaller set of groups your operator can use in a cardholder edit.
### Use cases
#### Choosing and setting a cardholder's default floor
Your client will first need to list all elevator groups, and the floors and access zones on those elevator groups, so that it can pick from them (if it knows them by name already) or present a list and allow a user to pick one if it is interactive.
Then it will need to send a PATCH back to the cardholder to set his or her default floor for an elevator group.
**Listing elevator groups and their access zones**
1. `GET /api`.
2. Follow the link at `features.cardholders.modifyPassengerDetails.href`, appending a search term such as `name=substring` to filter the selection if you have a lot of elevator groups.
3. Find the elevator group you are after, following the `next` link if you have lots.
4. Look in the `floorAccess` array for the floor names and access zone names you can use for picking the floor, and the access zone hrefs to use in the PATCH coming up.
**Setting a cardholder's default floor**
1. Find the href for the cardholder.
2. PATCH it with a request body containing the hrefs of the elevator groups and access zones you wish to set as that cardholder's defaults.
### Licensing
All the POSTs that override items require RESTOverrides.
If you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough information to let you find the item you want to override but they do not return its status.
If you have RESTCardholders but not RESTStatus in 8.60 or later, the GETs return cardholder-related fields.
In 8.50 and older, the GETs fail without RESTStatus.
The RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well as override it, you will need both.
## Search assignable elevator groups
> This searches the elevator groups that your privileges allow you to use in cardholders'\
> default floor and passenger type assignments, returning everything you need to make those\
> assignments.\
> \
> The result will contain no more than 100 or 1000 depending on your version, or as many as\
> you asked for; you should follow the \`next\` link, if it is present, to\
> collect the next batch.\
> \
> If your result set is empty it means your operator does not have the privilege to assign\
> elevator groups to cardholders ('Modify Passenger Details'). Perhaps there are no elevator\
> groups in the divisions in which your operator has that privilege.\
> \
> When you have loaded them all there will be no \`next\` link.\
> \
> Do not code this URL into your application. Take it from the \`href\` field in the\
> \`features.cardholders.modifyDefaultFloors\` section of \`/api\`.\
> \
> It requires the RESTCardholders licence.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Elevator Groups","description":"These methods give you read access to Elevator Groups.\n\nThe reason you would want that is to allocate default floors to cardholders. Each cardholder\ncan have one default floor per elevator group, so that when they badge into that group's lobby\narea the elevator system can arrange a car to take them to their favourite floor.\n\nEach elevator group only goes to certain floors, so to give a cardholder a default floor you\nneed to see which floors each elevator group services.\n\nCommand Centre represents floors with access zones. If an elevator car has two doors, front and\nrear, it may service two access zones on the same physical floor. A cardholder could pick\neither of those access zones as their default for that elevator group.\n\nThe main entry point is a paginated search that returns what you need to pick default floors for\na cardholder, limited by the privilege that enables that operation on a cardholder. That is the\ncall that you are most likely to need, but there is another that gives you all elevator groups\nthat your operator can view, rather than the smaller set of groups your operator can use in a\ncardholder edit.\n\n## Use cases\n\n### Choosing and setting a cardholder's default floor\n\nYour client will first need to list all elevator groups, and the floors and access zones on\nthose elevator groups, so that it can pick from them (if it knows them by name already) or present\na list and allow a user to pick one if it is interactive.\n\nThen it will need to send a PATCH back to the cardholder to set his or her default floor for an\nelevator group.\n\n#### Listing elevator groups and their access zones\n\n1. `GET /api`.\n2. Follow the link at `features.cardholders.modifyPassengerDetails.href`, appending a search term\n such as `name=substring` to filter the selection if you have a lot of elevator groups.\n3. Find the elevator group you are after, following the `next` link if you have lots.\n4. Look in the `floorAccess` array for the floor names and access zone names you can use for\n picking the floor, and the access zone hrefs to use in the\n [PATCH](cardholders#patch-api-cardholders-id-) coming up.\n\n#### Setting a cardholder's default floor\n\n1. [Find the href](cardholders) for the cardholder.\n\n2. [PATCH](cardholders#patch-api-cardholders-id-) it with a request body containing the\n hrefs of the elevator groups and access zones you wish to set as that cardholder's defaults.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.\n\nIf you have RESTCardholders but not RESTStatus in 8.60 or later, the GETs return\ncardholder-related fields.\n\nIn 8.50 and older, the GETs fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"sort":{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","-id","-name"]},"required":false,"description":"Changes the sort field between database ID and name.\n\nIf you prefix `id` or `name` with a minus sign (ASCII 45), the sort order is reversed.\n\nThere are two very strong reasons to sort by ID:\n\n1. Sorting by name carries a risk of missing or duplicating objects if your result set spans\n multiple pages and another operator is editing the database while your REST client is\n enumerating them. This is known as \"page drift.\" Sorting by ID does not carry that risk.\n2. Following a `next` link is _dramatically_ quicker when sorting by ID.\n\nWe _strongly_ recommend sorting by ID. In case you were still in doubt, we will do that by\ndefault in a future version of Command Centre.\n\nThe server silently ignores anything except the options listed here.\n"},"top":{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Limits the results to no more than this many items per page.\n\nOlder versions of Command Centre returned 100 items per page in the absence of this parameter. That is acceptable for GUI\napplications that will only display the first page, but for integrations that intend to\nproceed through the entire database it causes a lot of chatter.\n\n8.70 and later versions will default to 1000 items per request. This is about where a graph\nof throughput versus page size begins to level out.\n"},"name":{"name":"name","in":"query","schema":{"type":"string"},"description":"Limits the returned items to those with a name that matches this string. Without surrounding\nquotes or a percent sign or underscore, it is a substring match; surround the parameter with\ndouble quotes `\"...\"` for an exact match. Without quotes, a percent sign `%` will match any\nsubstring and an underscore will match any single character.\n\nThe search is always case-insensitive. Results are undefined if you do a substring search for\nthe empty string (`name=`). You will receive no items if you search for those with no name\n(`name=\"\"`), as all items must have a name.\n\nSearch parameters are ANDed together.\n"},"division":{"name":"division","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Limits the returned items to those that are in these divisions.\n\nThat includes all the items in those divisions' child divisions, because Command Centre treats\nitems as though they are also in their division's parent, and its parent, and so on up to the\nroot division.\n\nSeparate the IDs of the divisions in you are interested with commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n"},"directDivision":{"name":"directDivision","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Restricts items to those whose division is in this list.\n\nUnlike `division=`, it does not follow ancestry. That means it will limit the search to items\nthat are directly assigned to the divisions you list, whereas `division` (without the\n`direct`) will also include items that are assigned to their descendants.\n\nList the IDs of the divisions you are interested in separated by commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nBecause this is the first query parameter we added that contains a capital letter, this will\nbe the first time you have had to think about case sensitivity. `directDivision` works,\n`directdivision` does not.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n\nAdded in 9.20.\n"},"description":{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Limits the returned items to those with a description that matches this string. By default it\nis a substring match; surround it with double quotes `\"...\"` for an exact match. A `_` will\nmatch any single character, and a `%` will match any substring. With or without quotes,\nhaving either of these wildcards in the string will anchor it at both ends as though you had\nsurrounded it with `\"`.\n\nThe search is always case-insensitive. Results are undefined if you search for the empty\nstring (`description=` or `description=\"\"`).\n\nSearch parameters are ANDed together.\n"},"pos":{"name":"pos","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. You may see it in URLs you receive from the server, but you must never add it yourself."},"skip":{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. Do not add it to your queries."}},"schemas":{"ElevatorGroupFloorAccessDetail":{"title":"Elevator group floor access detail","description":"The [modify passenger details\nsearch](elevator-groups#get-api-elevator_groups-modify_passenger_details) returns an\narray of these. It is everything you need to pick a default floor for a cardholder, but not\neverything you get from an elevator group's detail page (which is linked as the href in this\nobject).\n","allOf":[{"$ref":"#/components/schemas/ElevatorGroupSummary"},{"type":"object","properties":{"division":{"type":"object","description":"The division containing this elevator group."},"floorAccess":{"description":"An array of objects describing the floors in this elevator group.\n\nThis example only has one floor. Production elevator systems often have more.\n","type":"array","items":{"type":"object","properties":{"floorNumber":{"type":"integer","minimum":1,"description":"This is Command Centre's internal identifier for the floor. Passengers do\nnot see it.\n"},"frontService":{"type":"boolean","description":"True iff the elevator car has a front-facing door and the elevator \nservices the floor with the front of the elevator.\n\nThis field requires the RESTStatus licence in versions up to and including 8.50.\nStarting with 8.60 it requires either the RESTStatus or the RESTOverrides\nlicence.\n"},"rearService":{"type":"boolean","description":"True iff the elevator car has a rear-facing door and the elevator \nservices the floor with the rear of the elevator.\n\nThis field requires the RESTStatus licence in versions up to and including 8.50.\nStarting with 8.60 it requires either the RESTStatus or the RESTOverrides\nlicence.\n"},"floorName":{"type":"string","description":"This is a friendly name that Command Centre presents to operators as the name of the\nfloor.\n"},"frontAccessZone":{"description":"The access zone into which the elevator car's front door opens. It will be\nmissing if the car's front door does not open on this floor.\n","type":"object","properties":{"id":{"type":"string","description":"An alphanumeric identifier, unique to the server. This is the ID to use in the `source`\nparameter of [event filters](events#get-api-events) and in the body of [status\nsubscriptions](items#status-subscriptions) when you are interested in events originating at this item.\n"},"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}},"rearAccessZone":{"description":"The access zone into which the elevator car's rear door opens. It will be\nmissing if the car's rear door does not open on this floor, or if the elevator\ngroup's `rearAccessEnabled` is false.\n","type":"object","properties":{"id":{"type":"string","description":"An alphanumeric identifier, unique to the server. This is the ID to use in the `source`\nparameter of [event filters](events#get-api-events) and in the body of [status\nsubscriptions](items#status-subscriptions) when you are interested in events originating at this item.\n"},"name":{"type":"string"},"href":{"type":"string","format":"uri-reference"}}}}}}}}]},"ElevatorGroupSummary":{"title":"Elevator group summary","description":"The [elevator group search](elevator-groups#get-api-elevator_groups) returns an array\nof these, if you don't use the `fields` parameter to ask for more. It is a subset of what\nyou get from the elevator group's detail page (which is linked as the href in this object)\nor the [modify passenger details\nsearch](elevator-groups#get-api-elevator_groups-modify_passenger_details).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [elevator group](models#elevatorgroupdetail) object for this\nelevator group.\n"},"name":{"type":"string"}}}}},"paths":{"/api/elevator_groups/modify_passenger_details":{"get":{"tags":["Elevator Groups"],"summary":"Search assignable elevator groups","description":"This searches the elevator groups that your privileges allow you to use in cardholders'\ndefault floor and passenger type assignments, returning everything you need to make those\nassignments.\n\nThe result will contain no more than 100 or 1000 depending on your version, or as many as\nyou asked for; you should follow the `next` link, if it is present, to\ncollect the next batch.\n\nIf your result set is empty it means your operator does not have the privilege to assign\nelevator groups to cardholders ('Modify Passenger Details'). Perhaps there are no elevator\ngroups in the divisions in which your operator has that privilege.\n\nWhen you have loaded them all there will be no `next` link.\n\nDo not code this URL into your application. Take it from the `href` field in the\n`features.cardholders.modifyDefaultFloors` section of `/api`.\n\nIt requires the RESTCardholders licence.\n","parameters":[{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/top"},{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"$ref":"#/components/parameters/description"},{"name":"fields","description":"This instructs the server to return only these fields in the search results. The values you can list are the same as the field\nnames in the details page. Using this you can return everything on the summary page that you\nwould find on the details page. Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not given\nthe parameter at all. Obviously only do that if you have more to add.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them. In 8.10\nand later you will only get what you asked for. If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"type":"string","enum":["href","name","description","division","floorAccess","defaults"]},"in":"query","required":false,"style":"form","explode":false},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success. An array of [elevator group](models#elevatorgroupflooraccessdetail)\nobjects and a `next` link for more.\n\nSee the note in the description about privileges if your result set is empty.\n","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ElevatorGroupFloorAccessDetail"}},"next":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}},"403":{"description":"The site does not have the RESTCardholders licence."}}}}}}
```
## Search elevator groups
> This returns the name and href of the elevator groups matching your search criteria. This\
> uses a different privilege from the \`modify\_passenger\_details\` call, so it may not return you\
> the groups you need. If your goal is to set cardholders' default floors, you should use that\
> call instead.\
> \
> The result will contain no more than 100 or 1000 (depending on your version), or as many as\
> you asked for; you should follow the \`next\` link, if it is present, to\
> collect the next batch.\
> \
> If your result set is empty it means your operator does not have the privilege to view any\
> elevator groups, such as 'View Site' or 'Edit Site'. Perhaps there are no elevator groups\
> in the divisions in which your operator has privileges, or your operator has no privileges\
> at all.\
> \
> When you have loaded them all there will be no \`next\` link.\
> \
> Do not code this URL into your application. Take it from the \`href\` field in the\
> \`features.elevators.elevatorGroups\` section of \`/api\`.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Elevator Groups","description":"These methods give you read access to Elevator Groups.\n\nThe reason you would want that is to allocate default floors to cardholders. Each cardholder\ncan have one default floor per elevator group, so that when they badge into that group's lobby\narea the elevator system can arrange a car to take them to their favourite floor.\n\nEach elevator group only goes to certain floors, so to give a cardholder a default floor you\nneed to see which floors each elevator group services.\n\nCommand Centre represents floors with access zones. If an elevator car has two doors, front and\nrear, it may service two access zones on the same physical floor. A cardholder could pick\neither of those access zones as their default for that elevator group.\n\nThe main entry point is a paginated search that returns what you need to pick default floors for\na cardholder, limited by the privilege that enables that operation on a cardholder. That is the\ncall that you are most likely to need, but there is another that gives you all elevator groups\nthat your operator can view, rather than the smaller set of groups your operator can use in a\ncardholder edit.\n\n## Use cases\n\n### Choosing and setting a cardholder's default floor\n\nYour client will first need to list all elevator groups, and the floors and access zones on\nthose elevator groups, so that it can pick from them (if it knows them by name already) or present\na list and allow a user to pick one if it is interactive.\n\nThen it will need to send a PATCH back to the cardholder to set his or her default floor for an\nelevator group.\n\n#### Listing elevator groups and their access zones\n\n1. `GET /api`.\n2. Follow the link at `features.cardholders.modifyPassengerDetails.href`, appending a search term\n such as `name=substring` to filter the selection if you have a lot of elevator groups.\n3. Find the elevator group you are after, following the `next` link if you have lots.\n4. Look in the `floorAccess` array for the floor names and access zone names you can use for\n picking the floor, and the access zone hrefs to use in the\n [PATCH](cardholders#patch-api-cardholders-id-) coming up.\n\n#### Setting a cardholder's default floor\n\n1. [Find the href](cardholders) for the cardholder.\n\n2. [PATCH](cardholders#patch-api-cardholders-id-) it with a request body containing the\n hrefs of the elevator groups and access zones you wish to set as that cardholder's defaults.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.\n\nIf you have RESTCardholders but not RESTStatus in 8.60 or later, the GETs return\ncardholder-related fields.\n\nIn 8.50 and older, the GETs fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"sort":{"name":"sort","in":"query","schema":{"type":"string","enum":["id","name","-id","-name"]},"required":false,"description":"Changes the sort field between database ID and name.\n\nIf you prefix `id` or `name` with a minus sign (ASCII 45), the sort order is reversed.\n\nThere are two very strong reasons to sort by ID:\n\n1. Sorting by name carries a risk of missing or duplicating objects if your result set spans\n multiple pages and another operator is editing the database while your REST client is\n enumerating them. This is known as \"page drift.\" Sorting by ID does not carry that risk.\n2. Following a `next` link is _dramatically_ quicker when sorting by ID.\n\nWe _strongly_ recommend sorting by ID. In case you were still in doubt, we will do that by\ndefault in a future version of Command Centre.\n\nThe server silently ignores anything except the options listed here.\n"},"top":{"name":"top","in":"query","required":false,"schema":{"type":"integer","minimum":1},"description":"Limits the results to no more than this many items per page.\n\nOlder versions of Command Centre returned 100 items per page in the absence of this parameter. That is acceptable for GUI\napplications that will only display the first page, but for integrations that intend to\nproceed through the entire database it causes a lot of chatter.\n\n8.70 and later versions will default to 1000 items per request. This is about where a graph\nof throughput versus page size begins to level out.\n"},"name":{"name":"name","in":"query","schema":{"type":"string"},"description":"Limits the returned items to those with a name that matches this string. Without surrounding\nquotes or a percent sign or underscore, it is a substring match; surround the parameter with\ndouble quotes `\"...\"` for an exact match. Without quotes, a percent sign `%` will match any\nsubstring and an underscore will match any single character.\n\nThe search is always case-insensitive. Results are undefined if you do a substring search for\nthe empty string (`name=`). You will receive no items if you search for those with no name\n(`name=\"\"`), as all items must have a name.\n\nSearch parameters are ANDed together.\n"},"division":{"name":"division","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Limits the returned items to those that are in these divisions.\n\nThat includes all the items in those divisions' child divisions, because Command Centre treats\nitems as though they are also in their division's parent, and its parent, and so on up to the\nroot division.\n\nSeparate the IDs of the divisions in you are interested with commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n"},"directDivision":{"name":"directDivision","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"}},"style":"form","explode":false,"description":"Restricts items to those whose division is in this list.\n\nUnlike `division=`, it does not follow ancestry. That means it will limit the search to items\nthat are directly assigned to the divisions you list, whereas `division` (without the\n`direct`) will also include items that are assigned to their descendants.\n\nList the IDs of the divisions you are interested in separated by commas. Item IDs are short\nalphanumeric strings, not URLs.\n\nBecause this is the first query parameter we added that contains a capital letter, this will\nbe the first time you have had to think about case sensitivity. `directDivision` works,\n`directdivision` does not.\n\nResults are undefined if you provide an ID that is not in the form of a division ID.\n\nSearch parameters are ANDed together.\n\nAdded in 9.20.\n"},"description":{"name":"description","in":"query","required":false,"schema":{"type":"string"},"description":"Limits the returned items to those with a description that matches this string. By default it\nis a substring match; surround it with double quotes `\"...\"` for an exact match. A `_` will\nmatch any single character, and a `%` will match any substring. With or without quotes,\nhaving either of these wildcards in the string will anchor it at both ends as though you had\nsurrounded it with `\"`.\n\nThe search is always case-insensitive. Results are undefined if you search for the empty\nstring (`description=` or `description=\"\"`).\n\nSearch parameters are ANDed together.\n"},"pos":{"name":"pos","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. You may see it in URLs you receive from the server, but you must never add it yourself."},"skip":{"name":"skip","in":"query","required":false,"schema":{"type":"integer"},"description":"Reserved for internal use. Do not add it to your queries."}},"schemas":{"ElevatorGroupSummary":{"title":"Elevator group summary","description":"The [elevator group search](elevator-groups#get-api-elevator_groups) returns an array\nof these, if you don't use the `fields` parameter to ask for more. It is a subset of what\nyou get from the elevator group's detail page (which is linked as the href in this object)\nor the [modify passenger details\nsearch](elevator-groups#get-api-elevator_groups-modify_passenger_details).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [elevator group](models#elevatorgroupdetail) object for this\nelevator group.\n"},"name":{"type":"string"}}}}},"paths":{"/api/elevator_groups":{"get":{"tags":["Elevator Groups"],"summary":"Search elevator groups","description":"This returns the name and href of the elevator groups matching your search criteria. This\nuses a different privilege from the `modify_passenger_details` call, so it may not return you\nthe groups you need. If your goal is to set cardholders' default floors, you should use that\ncall instead.\n\nThe result will contain no more than 100 or 1000 (depending on your version), or as many as\nyou asked for; you should follow the `next` link, if it is present, to\ncollect the next batch.\n\nIf your result set is empty it means your operator does not have the privilege to view any\nelevator groups, such as 'View Site' or 'Edit Site'. Perhaps there are no elevator groups\nin the divisions in which your operator has privileges, or your operator has no privileges\nat all.\n\nWhen you have loaded them all there will be no `next` link.\n\nDo not code this URL into your application. Take it from the `href` field in the\n`features.elevators.elevatorGroups` section of `/api`.\n","parameters":[{"$ref":"#/components/parameters/sort"},{"$ref":"#/components/parameters/top"},{"$ref":"#/components/parameters/name"},{"$ref":"#/components/parameters/division"},{"$ref":"#/components/parameters/directDivision"},{"$ref":"#/components/parameters/description"},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"description":"This instructs the server to return only these fields in the search results. The values you can list are the same as the field\nnames in the details page. Using this you can return everything on the summary page that you\nwould find on the details page. Separate values with commas.\n\nUse the special value `defaults` to return the fields you would have received had you not given\nthe parameter at all. Obviously only do that if you have more to add.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them. In 8.10\nand later you will only get what you asked for. If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"type":"string","enum":["href","name","shortName","description","division","notes","elevatorSystem","elevatorGroupNumber","floorAccess","rearAccessEnabled","groundFloorNumber","defaults"]}},{"$ref":"#/components/parameters/pos"},{"$ref":"#/components/parameters/skip"}],"responses":{"200":{"description":"Success. An array of [elevator group](models#elevatorgroupsummary) objects\nand a `next` link for more.\n","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ElevatorGroupSummary"}},"next":{"type":"object","properties":{"href":{"type":"string","format":"uri-reference"}}}}}}}},"403":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence. A server running\n8.60 or later is missing both the RESTStatus and RESTOverrides licences.\n"}}}}}}
```
## Get details of an elevator group
> This returns the detail of one elevator group.\
> \
> If you are setting cardholders' default floors, you should be using the\
> \`modify\_passenger\_details\` call rather than this one.
```json
{"openapi":"3.2.0","info":{"title":"Command Centre REST API","version":"2.0"},"tags":[{"name":"Elevator Groups","description":"These methods give you read access to Elevator Groups.\n\nThe reason you would want that is to allocate default floors to cardholders. Each cardholder\ncan have one default floor per elevator group, so that when they badge into that group's lobby\narea the elevator system can arrange a car to take them to their favourite floor.\n\nEach elevator group only goes to certain floors, so to give a cardholder a default floor you\nneed to see which floors each elevator group services.\n\nCommand Centre represents floors with access zones. If an elevator car has two doors, front and\nrear, it may service two access zones on the same physical floor. A cardholder could pick\neither of those access zones as their default for that elevator group.\n\nThe main entry point is a paginated search that returns what you need to pick default floors for\na cardholder, limited by the privilege that enables that operation on a cardholder. That is the\ncall that you are most likely to need, but there is another that gives you all elevator groups\nthat your operator can view, rather than the smaller set of groups your operator can use in a\ncardholder edit.\n\n## Use cases\n\n### Choosing and setting a cardholder's default floor\n\nYour client will first need to list all elevator groups, and the floors and access zones on\nthose elevator groups, so that it can pick from them (if it knows them by name already) or present\na list and allow a user to pick one if it is interactive.\n\nThen it will need to send a PATCH back to the cardholder to set his or her default floor for an\nelevator group.\n\n#### Listing elevator groups and their access zones\n\n1. `GET /api`.\n2. Follow the link at `features.cardholders.modifyPassengerDetails.href`, appending a search term\n such as `name=substring` to filter the selection if you have a lot of elevator groups.\n3. Find the elevator group you are after, following the `next` link if you have lots.\n4. Look in the `floorAccess` array for the floor names and access zone names you can use for\n picking the floor, and the access zone hrefs to use in the\n [PATCH](cardholders#patch-api-cardholders-id-) coming up.\n\n#### Setting a cardholder's default floor\n\n1. [Find the href](cardholders) for the cardholder.\n\n2. [PATCH](cardholders#patch-api-cardholders-id-) it with a request body containing the\n hrefs of the elevator groups and access zones you wish to set as that cardholder's defaults.\n\n## Licensing\n\nAll the POSTs that override items require RESTOverrides.\n\nIf you have RESTOverrides but not RESTStatus in 8.60 or later, the GETs return enough\ninformation to let you find the item you want to override but they do not return its status.\n\nIf you have RESTCardholders but not RESTStatus in 8.60 or later, the GETs return\ncardholder-related fields.\n\nIn 8.50 and older, the GETs fail without RESTStatus.\n\nThe RESTOverrides and RESTStatus licences do not overlap: to watch the status of an item as well\nas override it, you will need both."}],"servers":[{"url":"https://127.0.0.1:8904"}],"security":[{"API_key":[]},{"basic":[]}],"components":{"securitySchemes":{"API_key":{"type":"apiKey","name":"Authorization","in":"header","description":"\nClients authenticate by including a pre-shared API key in the `Authorization` header of each\nrequest after an authorisation method of `GGL-API-KEY`:\n\n`Authorization: GGL-API-KEY C774-B01F-D695-AA4B-215F-A158-AC22-ADEB`\n\nFor a fuller description see [API authentication](api-authentication).\n"},"basic":{"type":"http","scheme":"basic","description":"This is HTTP Basic authentication using a blank username and the API key as the password.\n\nExample: `Authorization: Basic OkM3NzQtQjAxRi1ENjk1LUFBNEItMjE1Ri1BMTU4LUFDMjItQURFQg==`\n\nThat example is equivalent to the example in the description of the api_Key method:\nprepending a colon to the API key beginning with `C774` then encoding it into Base64\nproduces the 56 characters beginning with `OkM3`.\n\nThe colon is a separator between a username, which is blank in our case, and the password,\nwhich is our API key.\n\nFor a fuller description see [API authentication](api-authentication)\n"}},"parameters":{"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"An internal identifier."}},"schemas":{"ElevatorGroupDetail":{"title":"Elevator group detail","description":"The [detail GET](elevator-groups#get-api-elevator_groups-id-) returns one of these.\n","allOf":[{"$ref":"#/components/schemas/ElevatorGroupSummary"},{"type":"object","properties":{"description":{"type":"string"},"notes":{"type":"string","description":"Because of their potential size, notes are only available by request. Use the 'fields'\nparameter:\n\n`?fields=defaults,notes,...`\n"},"shortName":{"type":"string","maxLength":16,"description":"Short names are not displayed by default. You must ask for them using the\n'fields' parameter:\n\n`?fields=shortname,...`.\n"},"elevatorGroupNumber":{"type":"integer","description":"The elevator system's internal identifier for this elevator group.\n"},"elevatorSystem":{"type":"object","properties":{"id":{"type":"string","description":"An alphanumeric identifier, unique to the server. This is the ID to use in the `source`\nparameter of [event filters](events#get-api-events) and in the body of [status\nsubscriptions](items#status-subscriptions) when you are interested in events originating at this item.\n"}}},"rearAccessEnabled":{"description":"True only if the elevator group uses rear doors on its cars to service the other side\nof the shaft.\n","type":"boolean"},"groundFloorNumber":{"type":"integer","minimum":1,"description":"The identifier of the floor that this elevator group calls 'ground'.\n"}}}]},"ElevatorGroupSummary":{"title":"Elevator group summary","description":"The [elevator group search](elevator-groups#get-api-elevator_groups) returns an array\nof these, if you don't use the `fields` parameter to ask for more. It is a subset of what\nyou get from the elevator group's detail page (which is linked as the href in this object)\nor the [modify passenger details\nsearch](elevator-groups#get-api-elevator_groups-modify_passenger_details).\n","properties":{"href":{"type":"string","format":"uri-reference","description":"A link to an [elevator group](models#elevatorgroupdetail) object for this\nelevator group.\n"},"name":{"type":"string"}}}},"responses":{"403nolicence":{"description":"A server running 8.50 or earlier is missing the RESTStatus licence. A server running 8.60\nor later is missing both the RESTStatus and RESTOverrides licences. One of those is enough\nfor this API call in 8.60 and later.\n"}}},"paths":{"/api/elevator_groups/{id}":{"get":{"tags":["Elevator Groups"],"summary":"Get details of an elevator group","description":"This returns the detail of one elevator group.\n\nIf you are setting cardholders' default floors, you should be using the\n`modify_passenger_details` call rather than this one.\n","parameters":[{"$ref":"#/components/parameters/id"},{"name":"fields","in":"query","required":false,"style":"form","explode":false,"description":"This instructs the server to return only these fields in the details page instead of the default set. The values you can list\nare the same as the field names you would see in the results. Use it to cut back on the size\nof the response. Separate values with commas.\n\nTreat the string matches as case-sensitive.\n\nIn v8.00 you will receive the href and internal ID even if you did not ask for them. In 8.10\nand later you will only get what you asked for. If you are going to send the `fields`\nparameter and need the href or ID, be explicit.\n","schema":{"type":"string","enum":["href","name","shortName","description","division","notes","elevatorSystem","elevatorGroupNumber","floorAccess","rearAccessEnabled","groundFloorNumber","defaults"]}}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ElevatorGroupDetail"}}}},"403":{"$ref":"#/components/responses/403nolicence"},"404":{"description":"The request's URL does not represent an elevator group, or the operator does not have a\nprivilege on the elevator group's division that allows viewing them, such as 'View Site'\nor 'Edit Site'.\n"}}}}}}
```
---
# 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 by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://help.security.gallagher.com/knowledge-hub/developer/rest-api/elevator-groups.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
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.